ZVISION: Add documentation

5 files changed, 133 insertions, 0 deletions

diff --git a/engines/zvision/cursor.h b/engines/zvision/cursor.h
index 77093c4daf..9a561fcac3 100644
--- a/engines/zvision/cursor.h
+++ b/engines/zvision/cursor.h
@@ -33,6 +33,10 @@ class String;
 
 namespace ZVision {
 
+/** 
+ * Utility class to parse and hold cursor data
+ * Modeled off Graphics::Cursor
+ */
 class ZorkCursor {
 public:
 	ZorkCursor();
diff --git a/engines/zvision/cursor_manager.h b/engines/zvision/cursor_manager.h
index fd61ac25be..1c09620b7e 100644
--- a/engines/zvision/cursor_manager.h
+++ b/engines/zvision/cursor_manager.h
@@ -64,20 +64,48 @@ private:
 	static const char *_zNemCursorFileNames[];
 
 public:
+	/** Creates the idle cursor and shows it */
 	void initialize();
 
+	/**
+	 * Parses a cursor name into a cursor file then creates and shows that cursor.
+	 * It will use the current _isCursorPushed state to choose the correct cursor
+	 *
+	 * @param cursorName    The name of a cursor. This *HAS* to correspond to one of the entries in _cursorNames[]
+	 */
 	void changeCursor(const Common::String &cursorName);
+	/**
+	 * Parses a cursor name into a cursor file then creates and shows that cursor.
+	 *
+	 * @param cursorName    The name of a cursor. This *HAS* to correspond to one of the entries in _cursorNames[] 
+	 * @param pushed        Should the cursor be pushed (true) or not pushed (false) (Another way to say it: down or up)
+	 */
 	void changeCursor(const Common::String &cursorName, bool pushed);
+	/**
+	 * Change the cursor to a certain push state. If the cursor is already in the specified push state, nothing will happen.
+	 *
+	 * @param pushed    Should the cursor be pushed (true) or not pushed (false) (Another way to say it: down or up)
+	 */
 	void cursorDown(bool pushed);
 
+	/** Set the cursor to 'Left Arrow'. It will retain the current _isCursorPushed state */
 	void setLeftCursor();
+	/** Set the cursor to 'Right Arrow'. It will retain the current _isCursorPushed state */
 	void setRightCursor();
+	/** Set the cursor to 'Up Arrow'. It will retain the current _isCursorPushed state */
 	void setUpCursor();
+	/** Set the cursor to 'Down Arrow'. It will retain the current _isCursorPushed state */
 	void setDownCursor();
 
+	/** Set the cursor to 'Idle'. It will retain the current _isCursorPushed state */
 	void revertToIdle();
 
 private:
+	/**
+	 * Calls CursorMan.replaceCursor() using the data in cursor
+	 *
+	 * @param cursor    The cursor to show
+	 */
 	void changeCursor(const ZorkCursor &cursor);
 };
 
diff --git a/engines/zvision/mouse_event.h b/engines/zvision/mouse_event.h
index 1fbd1603a3..5537bcc4e5 100644
--- a/engines/zvision/mouse_event.h
+++ b/engines/zvision/mouse_event.h
@@ -48,8 +48,24 @@ private:
 	Common::String _hoverCursor;
 
 public:
+	/**
+	 * Does a simple Rect::contains() using _hotspot
+	 *
+	 * @param point    The point to check against _hotspot
+	 * @return         The point is inside _hotspot (true) or not (false)
+	 */
 	bool withinHotspot(const Common::Point &point);
+	/**
+	 * Calls ScriptManager::setStateValue(_key, 1)
+	 *
+	 * @param engine    The base engine
+	 */
 	void onClick(ZVision *engine);
+	/**
+	 * Gets the name of the cursor that should be displayed when withinHotspot returns true
+	 *
+	 * @return    The name of the cursor. This should correspond to one of the names in CursorManager::_cursorNames[]
+	 */
 	const Common::String getHoverCursor() { return _hoverCursor; }
 };
 
diff --git a/engines/zvision/render_manager.h b/engines/zvision/render_manager.h
index a394586380..073a2f61e0 100644
--- a/engines/zvision/render_manager.h
+++ b/engines/zvision/render_manager.h
@@ -48,23 +48,45 @@ public:
 
 private:
 	OSystem *_system;
+
+	/** Width of the working window. Saved to prevent extraneous calls to _workingWindow.width() */
 	const int _workingWidth;
+	/** Height of the working window. Saved to prevent extraneous calls to _workingWindow.height() */
 	const int _workingHeight;
+	/** 
+	 * A Rectangle centered inside the actual window. All in-game coordinates
+	 * are given in this coordinate space. Also, all images are clipped to the
+	 * edges of this Rectangle
+	 */
 	const Common::Rect _workingWindow;
+	/** Used to warp the background image */
 	RenderTable _renderTable;
 
 	Common::SeekableReadStream *_currentBackground;
+	/** The (x1,y1) coordinates of the subRectangle of the background that is currently displayed on the screen */
 	Common::Point _backgroundOffset;
+	/** The width of the current background image */
 	uint16 _backgroundWidth;
+	/** The height of the current background image */
 	uint16 _backgroundHeight;
 
+	/** 
+	 * The "velocity" at which the background image is panning. We actually store the inverse of velocity (ms/pixel instead of pixels/ms)
+	 * because it allows you to accumulate whole pixels 'steps' instead of rounding pixels every frame
+	 */
 	int _backgroundInverseVelocity;
+	/** Holds any 'leftover' milliseconds between frames */
 	uint _accumulatedVelocityMilliseconds;
 
 	byte *_scaledVideoFrameBuffer;
 
 public:
 	void initialize();
+	/**
+	 * Rotates the background image in accordance to the current _backgroundInverseVelocity
+	 *
+	 * @param deltaTimeInMillis    The amount of time that has passed since the last frame
+	 */
 	void update(uint deltaTimeInMillis);
 
 	/**
@@ -97,15 +119,50 @@ public:
 	 */
 	void setBackgroundImage(const Common::String &fileName);
 
+	/**
+	 * Set the background position (_backgroundOffset). If the current RenderState is PANORAMA, the offset
+	 * will be in the horizontal direction. If the current RenderState is TILT, the offset will be in the
+	 * vertical direction. 
+	 *
+	 * This method will not render anything on the screen. So if nothing else is called that renders the 
+	 * background, the change won't be seen until next frame.
+	 *
+	 * @param offset The amount to offset the background
+	 */
 	void setBackgroundPosition(int offset);
 	
+	/**
+	 * Set the background scroll velocity. Negative velocities correspond to left / up scrolling and 
+	 * positive velocities correspond to right / down scrolling
+	 *
+	 * @param velocity    Velocity
+	 */
 	void setBackgroundVelocity(int velocity);
 
+	/**
+	 * Converts a point in screen coordinate space to image coordinate space
+	 *
+	 * @param point    Point in screen coordinate space
+	 * @return         Point in image coordinate space
+	 */
 	const Common::Point screenSpaceToImageSpace(const Common::Point &point);
 
 	RenderTable *getRenderTable();
 
 private:
+	/**
+	 * Renders a subRectangle of an image to the screen. The destinationRect and SubRect
+	 * will be clipped to image bound and to working window bounds
+	 *
+	 * @param buffer             Pointer to (0, 0) of the image data
+	 * @param imageWidth         The width of the original image (not of the subRectangle)
+	 * @param imageHeight        The width of the original image (not of the subRectangle)
+	 * @param horizontalPitch    The horizontal pitch of the original image
+	 * @param destinationX       The x coordinate (in working window space) of where to put the final image
+	 * @param destinationY       The y coordinate (in working window space) of where to put the final image
+	 * @param subRectangle       A rectangle representing the part of the image that should be rendered
+	 * @param wrap               Should the image wrap (tile) if it doesn't completely fill the screen?
+	 */
 	void renderSubRectToScreen(uint16 *buffer, uint32 imageWidth, uint32 imageHeight, uint32 horizontalPitch, uint32 destinationX, uint32 destinationY, Common::Rect subRectangle, bool wrap);
 
 	void moveBackground(int offset);
diff --git a/engines/zvision/zvision.h b/engines/zvision/zvision.h
index ca710804b0..58812d4d11 100644
--- a/engines/zvision/zvision.h
+++ b/engines/zvision/zvision.h
@@ -76,6 +76,11 @@ private:
 
 	Console *_console;
 	const ZVisionGameDescription *_gameDescription;
+	/** 
+	 * A Rectangle centered inside the actual window. All in-game coordinates
+	 * are given in this coordinate space. Also, all images are clipped to the
+	 * edges of this Rectangle
+	 */
 	const Common::Rect _workingWindow;
 	const Graphics::PixelFormat _pixelFormat;
 
@@ -110,17 +115,40 @@ public:
 	Common::RandomSource *getRandomSource() const;
 	ZVisionGameId getGameId() const;
 
+	/**
+	 * Play a video until it is finished. This is a blocking call. It will call
+	 * _clock.stop() when the video starts and _clock.start() when the video finishes.
+	 * It will also consume all events during video playback.
+	 *
+	 * @param videoDecoder    The video to play
+	 * @param destRect        Where to put the video. (In working window coords)
+	 * @param skippable       If true, the video can be skipped at any time using [Spacebar]
+	 */
 	void playVideo(Video::VideoDecoder &videoDecoder, const Common::Rect &destRect = Common::Rect(0, 0, 0, 0), bool skippable = true);
 
+	/**
+	 * Register a MouseEvent with the event system. These will be checked at every
+	 * MOUSE_UP, MOUSE_DOWN, MOUSE_MOVE, etc.
+	 *
+	 * @param event    The event to register
+	 */
 	void registerMouseEvent(const MouseEvent &event);
+	/** Remove all MouseEvents from the event system */
 	void clearAllMouseEvents();
 
+	/**
+	 * Utility method to cycle through all the cursors in the game. After
+	 * calling, use Left and Right arrows to cycle. Esc to quit. This is a
+	 * blocking function call.              
+	 */
 	void cycleThroughCursors();
 
 private:
 	void initialize();
 
+	/** Called every frame from ZVision::run() to process any events from EventMan */
 	void processEvents();
+
 	void onMouseDown(const Common::Point &pos);
 	void onMouseUp(const Common::Point &pos);
 	void onMouseMove(const Common::Point &pos);