X-Git-Url: http://git.tdb.fi/?a=blobdiff_plain;f=source%2Frenderable.h;h=b53fa9ac839307347bb614db7052dcfbe5a7a8cb;hb=db735acce6c9409fabcab80d87930263032af47c;hp=c055cefa65b989047ff0b324ab53259204ac77c1;hpb=f14435e58bfa0fa697a06ba9a454bb30cd37d9d8;p=libs%2Fgl.git

diff --git a/source/renderable.h b/source/renderable.h
index c055cefa..b53fa9ac 100644
--- a/source/renderable.h
+++ b/source/renderable.h
@@ -7,8 +7,22 @@
 namespace Msp {
 namespace GL {
 
+class Matrix;
 class Renderer;
 
+/**
+Base class for renderable objects.  All Renderables must support rendering with
+a Renderer, and may optionally provide support for standalone rendering.
+
+The render methods take a Tag to identify a render pass.  It is most commonly
+used together with Techniques and Pipelines to implement multipass rendering.
+
+The setup_frame and finish_frame methods provide a mechanism for performing
+once-per-frame operations.  This is most useful for effects, which may need to
+do auxiliary rendering.  With complex rendering hierarchies, these methods may
+be called multiple times for one frame, but it's guaranteed that no rendering
+will occur before a setup_frame call or after a finish_frame call.
+*/
 class Renderable
 {
 protected:
@@ -16,11 +30,28 @@ protected:
 public:
 	virtual ~Renderable() { }
 
-	/** Returns a key used for grouping Renderables in an InstanceScene. */
+	/** Returns a key used for grouping Renderables in an InstanceScene.  The
+	returned value is treated as opaque. */
 	virtual long get_instance_key() const { return 0; }
 
+	/** Returns the model matrix of the Renderable.  Null is returned if no such
+	matrix exists. */
+	virtual const Matrix *get_matrix() const { return 0; }
+
+	/** Called when starting to render a new frame. */
+	virtual void setup_frame() const { }
+
+	/** Called when a complete frame has been rendered. */
+	virtual void finish_frame() const { }
+
+	/** Renders the renderable without a renderer.  This can be convenient in
+	some simple cases, but most renderables don't need to implement this
+	method. */
 	virtual void render(const Tag & = Tag()) const;
-	virtual void render(Renderer &, const Tag & = Tag()) const;
+
+	/** Renders the renderable.  Implementors should take care to return the
+	renderer to the state it was in, for example by using Renderer::Push. */
+	virtual void render(Renderer &, const Tag & = Tag()) const = 0;
 };
 
 } // namespace Msp