Lots of comment updates

diff --git a/source/bindable.h b/source/bindable.h
index 8823de5c9773209a1642f5b763887e65ca7ea5d6..76c2fb528b7967839fa606a6c8a076ce190ee525 100644 (file)
--- a/source/bindable.h
+++ b/source/bindable.h
@@ -4,6 +4,10 @@
 namespace Msp {
 namespace GL {
 
 namespace Msp {
 namespace GL {
 

+/**
+A helper class for single-point binding.  Provides tracking of the currently
+bound object.
+*/

 template<typename T>
 class Bindable
 {
 template<typename T>
 class Bindable
 {

diff --git a/source/effect.h b/source/effect.h
index dfb369614c28c2388b1dcdd249e20e4d331224ec..7eeae682dffb00d593601b94e9eca82735a23f2e 100644 (file)
--- a/source/effect.h
+++ b/source/effect.h
@@ -9,7 +9,8 @@ namespace GL {
 
 /**
 Effects are used to wrap other renderables and give them additional visual
 
 /**
 Effects are used to wrap other renderables and give them additional visual

-properties.
+properties.  An Effect's render method should set up the necessary state, call
+the wrapped Renderable's render method, and clean up after itself.

 */
 class Effect: public Renderable
 {
 */
 class Effect: public Renderable
 {

diff --git a/source/mesh.h b/source/mesh.h
index 625cebe267e681aefe3d7949dc0b60f889c250ed..698ae60e53686dacf2210a5ac9d068a301a7a12e 100644 (file)
--- a/source/mesh.h
+++ b/source/mesh.h
@@ -12,6 +12,11 @@ namespace GL {
 class Buffer;
 class Renderer;
 
 class Buffer;
 class Renderer;
 

+/**
+Raw mesh data, consisting of a VertexArray and one or more Batches.  Though a
+Mesh can draw itself, it's usually used as part of Renderables rather than on
+its own.
+*/

 class Mesh
 {
        friend class MeshBuilder;
 class Mesh
 {
        friend class MeshBuilder;

diff --git a/source/object.h b/source/object.h
index 69759c80a7fde69b7ffe9ccc2a35abb064a758fa..8a707665c8871132e4c555f8a9fc88b5108a10c6 100644 (file)
--- a/source/object.h
+++ b/source/object.h
@@ -16,10 +16,12 @@ class Technique;
 class Texture;
 
 /**
 class Texture;
 
 /**

-Stores a Mesh together with a Technique to determine its appearance.
+Combines a Mesh with a Technique to give it an appearance.  The Technique will
+define which render passes the Object supports.

 
 

-It is possible to use a single Object for rendering multiple identical or
-similar objects.  See class ObjectInstance.
+In many cases, it's desirable to include multiple copies of an Object in a
+Scene, with different model matrices.  ObjectInstances can be used to alter the
+rendering of an object on a per-instance basis.

 */
 class Object: public Renderable
 {
 */
 class Object: public Renderable
 {


@@ -56,18 +58,12 @@ public:
        void set_technique(const Technique *);
        const Technique *get_technique() const { return technique.get(); }
 
        void set_technique(const Technique *);
        const Technique *get_technique() const { return technique.get(); }
 

-       /**
-       Renders the object.  A tag can be provided to render a non-default pass.
-       */

        virtual void render(const Tag &tag = Tag()) const;
 
        virtual void render(Renderer &, const Tag & = Tag()) const;
 
        virtual void render(const Tag &tag = Tag()) const;
 
        virtual void render(Renderer &, const Tag & = Tag()) const;
 

-       /**
-       Renders the object with an instance.  The instance's hook functions are
-       called before and after drawing the mesh.  A tag may also be given to render
-       a non-default pass.
-       */
+       /** Renders an instance of the object.  The instance's hook functions are
+       called before and after drawing the mesh. */

        virtual void render(Renderer &, const ObjectInstance &, const Tag & = Tag()) const;
 
 private:
        virtual void render(Renderer &, const ObjectInstance &, const Tag & = Tag()) const;
 
 private:

diff --git a/source/objectinstance.h b/source/objectinstance.h
index 5911dae57fb6f173210ea18936a8e353c11c9f54..3dc5da6a399432bafa62197b01ae0e19d7475f5f 100644 (file)
--- a/source/objectinstance.h
+++ b/source/objectinstance.h
@@ -11,9 +11,12 @@ class Object;
 class ProgramData;
 
 /**
 class ProgramData;
 
 /**

-Represents a single instance of an Object.  An application can derive another
-class from this and overload the hook functions to specify location and other
-instance-specific parameters for the rendered objects.
+Represents a single instance of an Object.  A derived class can overload the
+hook functions to specify a model matrix and other instance-specific parameters
+for the rendered objects.
+
+ObjectInstances can benefit from being put in an InstanceScene, which will
+render all instances of the same object consecutively.

 */
 class ObjectInstance: public Renderable
 {
 */
 class ObjectInstance: public Renderable
 {

diff --git a/source/pipeline.h b/source/pipeline.h
index d39bce5af9689523532412d05f3cff0eac75ec81..f8fdb5450b18d42eb621ff0fb80141918b9ecbc8 100644 (file)
--- a/source/pipeline.h
+++ b/source/pipeline.h
@@ -17,6 +17,28 @@ class DepthTest;
 class Lighting;
 class PostProcessor;
 
 class Lighting;
 class PostProcessor;
 

+/**
+Encapsulates all of the information used to produce a complete image in the
+framebuffer.  This is the highest level rendering class, combining Renderables
+with a camera, lights and some other influential objects.
+
+A Pipeline is also a Renderable itself.  Externally, it only exposes the
+default pass.  Internally, it can hold any number of passes, which are invoked
+in sequence when rendering the default pass is requested.  Each pass can have a
+Lighting, a DepthTest and a Blend to control how it is rendered.
+
+A Pipeline's render method should normally be called without a Renderer; it
+will create one itself, using the camera specified for the Pipeline.  If a
+Renderer is passed, its camera will be used instead.
+
+Renderables are rendered in the order they were added to the Pipeline.  While
+it's possible to remove renderables as well, using a Scene is recommended if
+frequent add/remove operations are needed.
+
+Pipelines may have post-processors to apply full-screen effects. Framebuffer
+objects are automatically used to pass render results to the post-processors.
+High dynamic range and multisample rendering can also be used.
+*/

 class Pipeline: public Renderable
 {
 public:
 class Pipeline: public Renderable
 {
 public:

diff --git a/source/postprocessor.h b/source/postprocessor.h
index d9489de2c65999a73644df932fe17c26f442d519..0666dd46c9cf2eb23e7bc4568cdea889fbf5c484 100644 (file)
--- a/source/postprocessor.h
+++ b/source/postprocessor.h
@@ -24,10 +24,10 @@ public:
        virtual void render(const Texture2D &color, const Texture2D &depth) = 0;
 
 protected:
        virtual void render(const Texture2D &color, const Texture2D &depth) = 0;
 
 protected:

-       /** Returns a vertex shader suitable for rendering a fullscreen quad.  Input
-       vertices are assumed to be in normalized device coordinates; no transform is
-       done.  The shader provides a varying vec2 texcoord for fragment a shader to
-       access textures. */
+       /** Returns a vertex shader suitable for rendering a full-screen quad.
+       Input vertices are assumed to be in normalized device coordinates; no
+       transform is performed.  The shader provides a varying vec2 texcoord for
+       a fragment shader to access textures. */

        static Shader &get_fullscreen_vertex_shader();
 
        /** Returns a mesh consisting of a single quad, covering the entire screen.
        static Shader &get_fullscreen_vertex_shader();
 
        /** Returns a mesh consisting of a single quad, covering the entire screen.

diff --git a/source/programdata.cpp b/source/programdata.cpp
index b8a272c0fc0bde8a3699a81e347115327c41938f..7334596c0d4873cfb550b995e5791d8b5236cd2d 100644 (file)
--- a/source/programdata.cpp
+++ b/source/programdata.cpp
@@ -46,6 +46,9 @@ void ProgramData::uniform(const string &name, Uniform *uni)
        UniformMap::iterator i = uniforms.find(name);
        if(i!=uniforms.end())
        {
        UniformMap::iterator i = uniforms.find(name);
        if(i!=uniforms.end())
        {

+               /* UniformBlock does not copy the uniforms, so existing blocks will be
+               left with stale pointers.  This is not a problem as long as no one stores
+               pointers to the blocks and expects them to stay valid. */

                delete i->second;
                i->second = uni;
                changes = VALUES_CHANGED;
                delete i->second;
                i->second = uni;
                changes = VALUES_CHANGED;

diff --git a/source/programdata.h b/source/programdata.h
index cf642e6141222d3033d80bc6d92e50ff6c99e863..38803c571ee2e210451ccc6abb3abd41ab005b23 100644 (file)
--- a/source/programdata.h
+++ b/source/programdata.h
@@ -17,7 +17,13 @@ class Vector3;
 class Vector4;
 
 /**
 class Vector4;
 
 /**

-Stores uniform variables for a shader program.
+Stores uniform variables for shader programs.  The uniforms are stored in a
+program-independent way, and UniformBlocks are created to match the uniform
+layouts of different programs.  If multiple programs have the same layout, the
+same block is used for them.
+
+The class is optimized for an access pattern where the set of uniforms and
+programs stays constants, with only the values changing.

 */
 class ProgramData
 {
 */
 class ProgramData
 {


@@ -93,9 +99,14 @@ private:
        void find_uniforms_for_block(Block &, const Program::UniformBlockInfo &) const;
        UniformBlock *create_block(const Program::UniformBlockInfo &) const;
        const UniformBlock *get_block(const Program &, const Program::UniformBlockInfo *) const;
        void find_uniforms_for_block(Block &, const Program::UniformBlockInfo &) const;
        UniformBlock *create_block(const Program::UniformBlockInfo &) const;
        const UniformBlock *get_block(const Program &, const Program::UniformBlockInfo *) const;

+

 public:
 public:

-       const UniformBlock *get_block(const Program &, const std::string &) const;
+       /** Returns a UniformBlock matching the program's layout.  If name is empty,
+       uniforms for the default uniform block (outside any uniform block
+       declarations) are returned. */
+       const UniformBlock *get_block(const Program &prog, const std::string &name) const;

 
 

+       /// Creates blocks for the currently bound program and applies them.

        void apply() const;
 };
 
        void apply() const;
 };
 

diff --git a/source/renderable.h b/source/renderable.h
index 78879a3d8030fb15fcd41136c16ec7c831541972..2342ae288cfed9b4d8fa61f25bf932ae47058540 100644 (file)
--- a/source/renderable.h
+++ b/source/renderable.h
@@ -12,6 +12,9 @@ class Renderer;
 /**
 Base class for renderable objects.  All Renderables must support rendering with
 a Renderer, and may optionally provide support for standalone rendering.
 /**
 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
 {
 */
 class Renderable
 {


@@ -20,10 +23,17 @@ protected:
 public:
        virtual ~Renderable() { }
 
 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; }
 
        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(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;
 };
 
        virtual void render(Renderer &, const Tag & = Tag()) const = 0;
 };
 

diff --git a/source/renderer.h b/source/renderer.h
index 501d1db3159667c42f92f3ecdfe2e85cb28fc1c4..dd54ca1691dfaf49233608ff85f2ff5de9e69440 100644 (file)
--- a/source/renderer.h
+++ b/source/renderer.h
@@ -24,7 +24,9 @@ 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
 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. */
+being drawn.  This avoids many unnecessary GL calls if consecutive renderables
+use the same resources.
+*/

 class Renderer
 {
 public:
 class Renderer
 {
 public:


@@ -92,7 +94,9 @@ public:
        void push_state();
        void pop_state();
 
        void push_state();
        void pop_state();
 

-       /** Prepares for temporarily bypassing the Renderer. */
+       /** Prepares for temporarily bypassing the Renderer by synchronizing the
+       current state with GL.  No additional call is necessary to resume using the
+       Renderer. */

        void escape();
 
        void draw(const Batch &);
        void escape();
 
        void draw(const Batch &);

diff --git a/source/tag.h b/source/tag.h
index ac31bce6839677620a96725dd11bc214c95132df..28b4fa010e8b0f12980df476f7ac8160a2c922fb 100644 (file)
--- a/source/tag.h
+++ b/source/tag.h
@@ -6,6 +6,10 @@
 namespace Msp {
 namespace GL {
 
 namespace Msp {
 namespace GL {
 

+/**
+Provides transparent string-to-hash conversion for faster comparison.  An empty
+string is guaranteed to have an id of 0.
+*/

 struct Tag
 {
        unsigned id;
 struct Tag
 {
        unsigned id;

diff --git a/source/uniformblock.h b/source/uniformblock.h
index 12b24de3d06a810aa16040b49d2df973e53eba5d..1a277106040f3757dd6d3c143f61f55137a08266 100644 (file)
--- a/source/uniformblock.h
+++ b/source/uniformblock.h
@@ -16,6 +16,10 @@ class Uniform;
 class Vector3;
 class Vector4;
 
 class Vector3;
 class Vector4;
 

+/**
+Stores uniforms with a specific layout.  Both named and default uniform blocks
+are supported.
+*/

 class UniformBlock: public Bufferable
 {
 private:
 class UniformBlock: public Bufferable
 {
 private: