Update and improve documentation

[libs/gl.git] / source / render / renderer.h

diff --git a/source/render/renderer.h b/source/render/renderer.h
index eb23e96dab8deb8d8c10ec384bca387ef21b7085..001ec7e1ca11864c172cef70219872de36fdbb6d 100644 (file)
--- a/source/render/renderer.h
+++ b/source/render/renderer.h
@@ -27,22 +27,24 @@ class Texture;
 class VertexSetup;
 
 /**
-A class for supervising the rendering process.  While many Renderables (in
-particular, Objects and Scenes) can by rendered without a Renderer, using one
-will often be more efficient.  This is especially true for ObjectInstances.
-
-The Renderer works by deferring GL state changes until something is actually
-being drawn.  This avoids many unnecessary GL calls if consecutive renderables
-use the same resources.
-
-A state stack is provided to help with state scoping.  Typically a Renderable
-will push the current state on entry, set whatever state it requires, render
-itself, and pop the state when it's done.  An RAII helper class is provided for
-the push/pop operation.
+Rendering supervisor.  This is the primary interface for setting state and
+issuing draw commands.
+
+The Renderer class allows setting textures and uniform values by names (using
+ProgramData for the latter).  The names are resolved into binding points when
+the resources are needed for a draw command.
+
+A state stack is provided to help with state management in render graphs.
+Renderables can save the state by pushing it on the stack before beginning
+their work, and pop it afterwards to restore it without disturbing state set
+by outer scopes.
 */
 class Renderer
 {
 public:
+       /**
+       RAII helper class for pushing state on the stack.
+       */
        class Push
        {
        private:
@@ -137,13 +139,13 @@ public:
 
        DEPRECATED void set_lighting(const Lighting *);
 
-       /** Sets the shader program to use.  An initial set of data can be set as
-       well, with the same semantics as add_shader_data. */
+       /** Sets the shader program to use.  As a convenience, uniform values may be
+       specified at the same time. */
        void set_shader_program(const Program *prog, const ProgramData *data = 0);
 
-       /** Adds another set of data to be use with shader programs.  The data is
-       independent of any shader program changes and remains in effect until the
-       Renderer state is popped. */
+       /** Adds uniform values, which will be available for shader programs.  If
+       multiple ProgramData objects with the same uniforms are added, the one added
+       last will be used. */
        void add_shader_data(const ProgramData &data);
 
        DEPRECATED void flush_shader_data() { flush_shader_data_(); }
@@ -176,10 +178,15 @@ public:
 
        void clear(const ClearValue *);
 
+       /** Draws a batch of primitives.  A shader must be active. */
        void draw(const Batch &);
+
+       /** Draws multiple instances of a batch of primitives.  A shader must be active. */
        void draw_instanced(const Batch &, unsigned);
 
-       void resolve_multisample(Framebuffer &);
+       /** Resolves multisample attachments from the active framebuffer into
+       target. */
+       void resolve_multisample(Framebuffer &target);
 
        void begin_query(const QueryPool &, unsigned);
        void end_query(const QueryPool &, unsigned);