Lots of comment updates

[libs/gl.git] / source / renderable.h

diff --git a/source/renderable.h b/source/renderable.h
index 8e31d5a7ac79e0f4a379b581da4b68ef37823c05..2342ae288cfed9b4d8fa61f25bf932ae47058540 100644 (file)
--- a/source/renderable.h
+++ b/source/renderable.h
@@ -1,10 +1,3 @@
-/* $Id$
-
-This file is part of libmspgl
-Copyright © 2007, 2011  Mikko Rasa, Mikkosoft Productions
-Distributed under the LGPL
-*/
-
 #ifndef MSP_GL_RENDERABLE_H_
 #define MSP_GL_RENDERABLE_H_
 
@@ -16,6 +9,13 @@ namespace GL {
 
 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.
+*/
 class Renderable
 {
 protected:
@@ -23,8 +23,18 @@ protected:
 public:
        virtual ~Renderable() { }
 
+       /** 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; }
+
+       /** 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