SCI32: Clean up ScreenItem

* Rewrap comments to 80 columns
* Clarify comments where possible
* Use smart pointers where appropriate

1 files changed, 76 insertions, 97 deletions

diff --git a/engines/sci/graphics/screen_item32.h b/engines/sci/graphics/screen_item32.h
index cdde2d3965..5acf759c32 100644
--- a/engines/sci/graphics/screen_item32.h
+++ b/engines/sci/graphics/screen_item32.h
@@ -49,22 +49,20 @@ class SegManager;
 #pragma mark ScreenItem
 
 /**
- * A ScreenItem is the engine-side representation of a
- * game script View.
+ * A ScreenItem is the engine-side representation of a game script View.
  */
 class ScreenItem {
 private:
 	/**
-	 * A serial used for screen items that are generated
-	 * inside the graphics engine, rather than the
-	 * interpreter.
+	 * A serial used for screen items that are generated inside the graphics
+	 * engine, rather than the interpreter.
 	 */
 	static uint16 _nextObjectId;
 
 	/**
-	 * A serial used to identify the creation order of
-	 * screen items, to ensure a stable sort order for
-	 * screen items with identical priorities and z-indexes.
+	 * A serial used to identify the creation order of screen items, to ensure a
+	 * stable sort order for screen items with identical priorities and
+	 * z-indexes.
 	 */
 	static uint32 _nextCreationId;
 
@@ -75,160 +73,145 @@ public:
 	reg_t _plane;
 
 	/**
-	 * Scaling data used to calculate the final screen
-	 * dimensions of the screen item as well as the scaling
-	 * ratios used when drawing the item to screen.
+	 * Scaling data used to calculate the final screen dimensions of the screen
+	 * item as well as the scaling ratios used when drawing the item to screen.
 	 */
 	ScaleInfo _scale;
 
 private:
 	/**
-	 * The position & dimensions of the screen item in
-	 * screen coordinates. This rect includes the offset
-	 * of the parent plane, but is not clipped to the
-	 * screen, so may include coordinates that are
-	 * offscreen.
+	 * The position & dimensions of the screen item in screen coordinates. This
+	 * rect includes the offset of the parent plane, but is not clipped to the
+	 * screen, so may include coordinates that are offscreen.
 	 */
 	Common::Rect _screenItemRect;
 
 	/**
-	 * If true, the `_insetRect` rectangle will be used
-	 * when calculating the dimensions of the screen item
-	 * instead of the cel's intrinsic width and height.
+	 * If true, the `_insetRect` rectangle will be used when calculating the
+	 * dimensions of the screen item instead of the cel's intrinsic width and
+	 * height.
 	 *
-	 * In other words, using an inset rect means that
-	 * the cel is cropped to the dimensions given in
-	 * `_insetRect`.
+	 * In other words, using an inset rect means that the cel is cropped to the
+	 * dimensions given in `_insetRect`.
 	 */
 	bool _useInsetRect;
 
 	/**
-	 * The cropping rectangle used when `_useInsetRect`
-	 * is true.
+	 * The cropping rectangle used when `_useInsetRect` is true.
 	 *
-	 * `_insetRect` is also used to describe the fill
-	 * rectangle of a screen item with a CelObjColor
-	 * cel.
+	 * `_insetRect` is also used to describe the fill rectangle of a screen item
+	 * with a CelObjColor cel.
 	 */
 	Common::Rect _insetRect;
 
 	/**
-	 * The z-index of the screen item in pseudo-3D space.
-	 * Higher values are drawn on top of lower values.
+	 * The z-index of the screen item in pseudo-3D space. Higher values are
+	 * drawn on top of lower values.
 	 */
 	int _z;
 
 	/**
-	 * Sets the common properties of a screen item that must
-	 * be set both during creation and update of a screen
-	 * item.
+	 * Sets the common properties of a screen item that must be set both during
+	 * creation and update of a screen item.
 	 */
 	void setFromObject(SegManager *segMan, const reg_t object, const bool updateCel, const bool updateBitmap);
 
 public:
 	/**
-	 * The creation order number, which ensures a stable
-	 * sort when screen items with identical priorities and
-	 * z-indexes are added to the screen item list.
+	 * The creation order number, which ensures a stable sort when screen items
+	 * with identical priorities and z-indexes are added to the screen item
+	 * list.
 	 */
 	uint32 _creationId;
 
 	/**
-	 * A descriptor for the cel object represented by the
-	 * screen item.
+	 * A descriptor for the cel object represented by the screen item.
 	 */
 	CelInfo32 _celInfo;
 
 	/**
-	 * The cel object used to actually render the screen
-	 * item. This member is populated by calling
-	 * `getCelObj`.
+	 * The cel object used to actually render the screen item. This member is
+	 * populated by calling `getCelObj`.
 	 */
-	mutable CelObj *_celObj;
+	mutable Common::ScopedPtr<CelObj> _celObj;
 
 	/**
-	 * If set, the priority for this screen item is fixed
-	 * in place. Otherwise, the priority of the screen item
-	 * is calculated from its y-position + z-index.
+	 * If set, the priority for this screen item is fixed in place. Otherwise,
+	 * the priority of the screen item is calculated from its y-position +
+	 * z-index.
 	 */
 	bool _fixedPriority;
 
 	/**
-	 * The rendering priority of the screen item, relative
-	 * only to the other screen items within the same plane.
-	 * Higher priorities are drawn above lower priorities.
+	 * The rendering priority of the screen item, relative only to the other
+	 * screen items within the same plane. Higher priorities are drawn above
+	 * lower priorities.
 	 */
 	int16 _priority;
 
 	/**
-	 * The top-left corner of the screen item, in game
-	 * script coordinates, relative to the parent plane.
+	 * The top-left corner of the screen item, in game script coordinates,
+	 * relative to the parent plane.
 	 */
 	Common::Point _position;
 
 	/**
-	 * The associated View script object that was
-	 * used to create the ScreenItem, or a numeric
-	 * value in the case of a ScreenItem that was
-	 * generated outside of the VM.
+	 * The associated View script object that was used to create the ScreenItem,
+	 * or a numeric value in the case of a ScreenItem that was generated by the
+	 * kernel.
 	 */
 	reg_t _object;
 
 	/**
-	 * For screen items representing picture resources,
-	 * the resource ID of the picture.
+	 * For screen items representing picture resources, the resource ID of the
+	 * picture.
 	 */
 	GuiResourceId _pictureId;
 
 	/**
 	 * Flags indicating the state of the screen item.
-	 * - `created` is set when the screen item is first
-	 *   created, either from a VM object or from within the
-	 *   engine itself
-	 * - `updated` is set when `created` is not already set
-	 *   and the screen item is updated from a VM object
-	 * - `deleted` is set by the parent plane, if the parent
-	 *   plane is a pic type and its picture resource ID has
-	 *   changed
+	 * - `created` is set when the screen item is first created, either from a
+	 *   VM object or from within the kernel
+	 * - `updated` is set when `created` is not already set and the screen item
+	 *   is updated from a VM object
+	 * - `deleted` is set by the parent plane, if the parent plane is a pic type
+	 *   and its picture resource ID has changed
 	 */
 	int _created, _updated, _deleted;
 
 	/**
-	 * For screen items that represent picture cels, this
-	 * value is set to match the `_mirrorX` property of the
-	 * parent plane and indicates that the cel should be
-	 * drawn horizontally mirrored. For final drawing, it is
-	 * XORed with the `_mirrorX` property of the cel object.
-	 * The cel object's `_mirrorX` property comes from the
-	 * resource data itself.
+	 * For screen items that represent picture cels, this value is set to match
+	 * the `_mirrorX` property of the parent plane and indicates that the cel
+	 * should be
+	 * drawn horizontally mirrored. For final drawing, it is XORed with the
+	 * `_mirrorX` property of the cel object. The cel object's `_mirrorX`
+	 * property comes from the resource data.
 	 */
 	bool _mirrorX;
 
 	/**
-	 * The scaling ratios to use when drawing this screen
-	 * item. These values are calculated according to the
-	 * scale info whenever the screen item is updated.
+	 * The scaling ratios to use when drawing this screen item. These values are
+	 * calculated according to the scale info whenever the screen item is
+	 * updated.
 	 */
 	Ratio _ratioX, _ratioY;
 
 	/**
-	 * The top-left corner of the screen item, in screen
-	 * coordinates.
+	 * The top-left corner of the screen item, in screen coordinates.
 	 */
 	Common::Point _scaledPosition;
 
 	/**
-	 * The position & dimensions of the screen item in
-	 * screen coordinates. This rect includes the offset of
-	 * the parent plane and is clipped to the screen.
+	 * The position & dimensions of the screen item in screen coordinates. This
+	 * rect includes the offset of the parent plane and is clipped to the
+	 * screen.
 	 */
 	Common::Rect _screenRect;
 
 	/**
-	 * Whether or not the screen item should be drawn
-	 * with black lines drawn every second line. This is
-	 * used when pixel doubling videos to improve apparent
-	 * sharpness at the cost of your eyesight.
+	 * Whether or not the screen item should be drawn with black lines drawn
+	 * every second line. This is used when pixel doubling videos to improve
+	 * apparent sharpness at the cost of your eyesight.
 	 */
 	bool _drawBlackLines;
 
@@ -242,7 +225,6 @@ public:
 	ScreenItem(const reg_t plane, const CelInfo32 &celInfo, const Common::Rect &rect);
 	ScreenItem(const reg_t plane, const CelInfo32 &celInfo, const Common::Point &position, const ScaleInfo &scaleInfo);
 	ScreenItem(const ScreenItem &other);
-	~ScreenItem();
 	void operator=(const ScreenItem &);
 
 	inline bool operator<(const ScreenItem &other) const {
@@ -337,39 +319,36 @@ public:
 	}
 
 	/**
-	 * Calculates the dimensions and scaling parameters for
-	 * the screen item, using the given plane as the parent
-	 * plane for screen rect positioning.
+	 * Calculates the dimensions and scaling parameters for the screen item,
+	 * using the given plane as the parent plane for screen rect positioning.
 	 *
-	 * @note This method was called Update in SCI engine.
+	 * @note This method was called Update in SSCI.
 	 */
 	void calcRects(const Plane &plane);
 
 	/**
-	 * Retrieves the corresponding cel object for this
-	 * screen item. If a cel object does not already exist,
-	 * one will be created and assigned.
+	 * Retrieves the corresponding cel object for this screen item. If a cel
+	 * object does not already exist, one will be created and assigned.
 	 */
 	CelObj &getCelObj() const;
 
 	void printDebugInfo(Console *con) const;
 
 	/**
-	 * Updates the properties of the screen item from a
-	 * VM object.
+	 * Updates the properties of the screen item from a VM object.
 	 */
 	void update(const reg_t object);
 
 	/**
-	 * Updates the properties of the screen item for one not belonging
-	 * to a VM object. Originally GraphicsMgr::UpdateScreenItem.
+	 * Updates the properties of the screen item for one not belonging to a VM
+	 * object. Originally GraphicsMgr::UpdateScreenItem.
 	 */
 	void update();
 
 	/**
-	 * Gets the "now seen" rect for the screen item, which
-	 * represents the current size and position of the
-	 * screen item on the screen in script coordinates.
+	 * Gets the "now seen" rect for the screen item, which represents the
+	 * current size and position of the screen item on the screen in script
+	 * coordinates.
 	 */
 	Common::Rect getNowSeenRect(const Plane &plane) const;
 };