WINTERMUTE: Add atleast some comments to the renderTicket-system.

2 files changed, 47 insertions, 3 deletions

diff --git a/engines/wintermute/base/gfx/osystem/base_render_osystem.h b/engines/wintermute/base/gfx/osystem/base_render_osystem.h
index bf2914b430..928a52d4fc 100644
--- a/engines/wintermute/base/gfx/osystem/base_render_osystem.h
+++ b/engines/wintermute/base/gfx/osystem/base_render_osystem.h
@@ -38,6 +38,25 @@
 namespace Wintermute {
 class BaseSurfaceOSystem;
 class RenderTicket;
+/**
+ * A 2D-renderer implementation for WME.
+ * This renderer makes use of a "ticket"-system, where all draw-calls
+ * are stored as tickets until flip() is called, and compared against the tickets
+ * from last frame, to determine which calls were the same as last round
+ * (i.e. in the exact same order, with the exact same arguments), and thus
+ * figure out which parts of the screen need to be redrawn.
+ *
+ * Important concepts to handle here, is the ordered number of any ticket
+ * which is called the "drawNum", every frame this starts from scratch, and
+ * then the incoming tickets created from the draw-calls are checked to see whether
+ * they came before, on, or after the drawNum they had last frame. Everything else
+ * being equal, this information is then used to check whether the draw order changed,
+ * which will then create a need for redrawing, as we draw with an alpha-channel here.
+ *
+ * There is also a draw path that draws without tickets, for debugging purposes,
+ * as well as to accomodate situations with large enough amounts of draw calls,
+ * that there will be too much overhead involved with comparing the generated tickets.
+ */
 class BaseRenderOSystem : public BaseRenderer {
 public:
 	BaseRenderOSystem(BaseGame *inGame);
@@ -59,6 +78,11 @@ public:
 
 	void invalidateTicket(RenderTicket *renderTicket);
 	void invalidateTicketsFromSurface(BaseSurfaceOSystem *surf);
+	/**
+	 * Insert a ticket into the queue, adding a dirty rect if it's
+	 * new, or out-of-order from last draw from the ticket.
+	 * param renderTicket the ticket to be added.
+	 */
 	void drawFromTicket(RenderTicket *renderTicket);
 
 	bool setViewport(int left, int top, int right, int bottom) override;
@@ -79,11 +103,18 @@ public:
 	virtual bool startSpriteBatch() override;
 	virtual bool endSpriteBatch() override;
 	void endSaveLoad();
-	void drawSurface(BaseSurfaceOSystem *owner, const Graphics::Surface *surf, Common::Rect *srcRect, Common::Rect *dstRect, TransformStruct &transform); 
+	void drawSurface(BaseSurfaceOSystem *owner, const Graphics::Surface *surf, Common::Rect *srcRect, Common::Rect *dstRect, TransformStruct &transform);
 	void repeatLastDraw(int offsetX, int offsetY, int numTimesX, int numTimesY);
 	BaseSurface *createSurface() override;
 private:
-	void addDirtyRect(const Common::Rect &rect) ;
+	/**
+	 * Mark a specified rect of the screen as dirty.
+	 * @param rect the region to be marked as dirty
+	 */
+	void addDirtyRect(const Common::Rect &rect);
+	/**
+	 * Traverse the tickets that are dirty, and draw them
+	 */
 	void drawTickets();
 	// Non-dirty-rects:
 	void drawFromSurface(RenderTicket *ticket);
@@ -96,7 +127,7 @@ private:
 	RenderTicket *_previousTicket;
 
 	bool _needsFlip;
-	uint32 _drawNum;
+	uint32 _drawNum; ///< The global number of the current draw-operation.
 	Common::Rect _renderRect;
 	Graphics::Surface *_renderSurface;
 	Graphics::Surface *_blankSurface;
diff --git a/engines/wintermute/base/gfx/osystem/render_ticket.h b/engines/wintermute/base/gfx/osystem/render_ticket.h
index b1313e932d..875102d01c 100644
--- a/engines/wintermute/base/gfx/osystem/render_ticket.h
+++ b/engines/wintermute/base/gfx/osystem/render_ticket.h
@@ -36,6 +36,19 @@
 namespace Wintermute {
 
 class BaseSurfaceOSystem;
+/**
+ * A single RenderTicket.
+ * A render ticket is a collection of the data and draw specifications made
+ * for a single draw-call in the OSystem-backend for WME. The ticket additionally
+ * holds the order in which this call was made, so that it can be detected if
+ * the same call is done in the following frame. Thus allowing us to potentially 
+ * skip drawing the same region again, unless anything has changed. Since a surface 
+ * can have a potentially large amount of draw-calls made to it, at varying rotation, 
+ * zoom, and crop-levels we also need to hold a copy of the necessary data. 
+ * (Video-surfaces may even change their data). The promise that is made when a ticket 
+ * is created is that what the state was of the surface at THAT point, is what will end 
+ * up on screen at flip() time.
+ */
 class RenderTicket {
 public:
 	RenderTicket(BaseSurfaceOSystem *owner, const Graphics::Surface *surf, Common::Rect *srcRect, Common::Rect *dstRest, TransformStruct transform);