From 7ff86ba6f9ce7a549a1b327396bce166de083803 Mon Sep 17 00:00:00 2001
From: RichieSams
Date: Sat, 21 Sep 2013 00:31:59 -0500
Subject: ZVISION: Add documentation for RlfAnimation

---
 engines/zvision/rlf_animation.h | 67 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

diff --git a/engines/zvision/rlf_animation.h b/engines/zvision/rlf_animation.h
index 133bf3913e..3f205d9666 100644
--- a/engines/zvision/rlf_animation.h
+++ b/engines/zvision/rlf_animation.h
@@ -77,21 +77,88 @@ public:
 	uint height() { return _height; }
 	uint32 frameTime() { return _frameTime; }
 
+	/**
+	 * Seeks to the frameNumber and updates the internal Surface with
+	 * the new frame data. If frameNumber == -1, it only sets _currentFrame,
+	 * the internal Surface is unchanged. This function requires _stream = false
+	 *
+	 * @param frameNumber    The frame number to seek to
+	 */
 	void seekToFrame(int frameNumber);
 
+	/**
+	 * Returns the pixel data of the frame specified. It will try to use
+	 * getNextFrame() if possible. If not, it uses seekToFrame() to
+	 * update the internal Surface and then returns a pointer to it.
+	 * This function requires _stream = false
+	 *
+	 * @param frameNumber    The frame number to get data for
+	 * @return               A pointer to the pixel data. Do NOT delete this.
+	 */
 	const Graphics::Surface *getFrameData(uint frameNumber);
+	/**
+	 * Returns the pixel data of the next frame. It is up to the user to
+	 * check if the next frame is valid before calling this.
+	 * IE. Use endOfAnimation()
+	 *
+	 * @return    A pointer to the pixel data. Do NOT delete this.
+	 */
 	const Graphics::Surface *getNextFrame();
 
+	/**
+	 * @return Is the currentFrame is the last frame in the animation?
+	 */
 	bool endOfAnimation() { return _currentFrame == (int)_frameCount - 1; }
 
 private:
+	/**
+	 * Reads in the header of the RLF file
+	 *
+	 * @return    Will return false if the header magic number is wrong
+	 */
 	bool readHeader();
+	/**
+	 * Reads the next frame from the RLF file, stores the data in
+	 * a Frame object, then returns the object
+	 *
+	 * @return    A Frame object representing the frame data
+	 */
 	Frame readNextFrame();
 
+	/**
+	 * Applies the frame corresponding to frameNumber on top of _currentFrameBuffer.
+	 * This function requires _stream = false so it can look up the Frame object
+	 * referenced by frameNumber.
+	 *
+	 * @param frameNumber    The frame number to apply to _currentFrameBuffer
+	 */
 	void applyFrameToCurrent(uint frameNumber);
+	/**
+	 * Applies the data from a Frame object on top of a _currentFrameBuffer.
+	 *
+	 * @param frame    A Frame object to apply to _currentFrameBuffer
+	 */
 	void applyFrameToCurrent(const RlfAnimation::Frame &frame);
 
+	/**
+	 * Decode frame data that uses masked run length encoding. This is the encoding
+	 * used by P-frames.
+	 *
+	 * @param source        The source pixel data
+	 * @param dest          The destination buffer
+	 * @param sourceSize    The size of the source pixel data
+	 * @param destSize      The size of the destination buffer
+	 */
 	void decodeMaskedRunLengthEncoding(int8 *source, int8 *dest, uint32 sourceSize, uint32 destSize) const;
+	/**
+	 * Decode frame data that uses simple run length encoding. This is the encoding
+	 * used by I-frames.
+	 *
+	 * @param source        The source pixel data
+	 * @param dest          The destination buffer
+	 * @param sourceSize    The size of the source pixel data
+	 * @param destSize      The size of the destination buffer
+	 */
 	void decodeSimpleRunLengthEncoding(int8 *source, int8 *dest, uint32 sourceSize, uint32 destSize) const;
 };
 
-- 
cgit v1.2.3