From: Mikko Rasa Date: Sun, 26 Aug 2012 21:27:03 +0000 (+0300) Subject: Lots of comment updates X-Git-Url: http://git.tdb.fi/?p=libs%2Fgl.git;a=commitdiff_plain;h=904de4f7fd994886adbd3a6c03bc1b7c14ebc562 Lots of comment updates --- diff --git a/source/bindable.h b/source/bindable.h index 8823de5c..76c2fb52 100644 --- a/source/bindable.h +++ b/source/bindable.h @@ -4,6 +4,10 @@ namespace Msp { namespace GL { +/** +A helper class for single-point binding. Provides tracking of the currently +bound object. +*/ template class Bindable { diff --git a/source/effect.h b/source/effect.h index dfb36961..7eeae682 100644 --- 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 -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 { diff --git a/source/mesh.h b/source/mesh.h index 625cebe2..698ae60e 100644 --- a/source/mesh.h +++ b/source/mesh.h @@ -12,6 +12,11 @@ namespace GL { 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; diff --git a/source/object.h b/source/object.h index 69759c80..8a707665 100644 --- a/source/object.h +++ b/source/object.h @@ -16,10 +16,12 @@ class Technique; 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 { @@ -56,18 +58,12 @@ public: 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; - /** - 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: diff --git a/source/objectinstance.h b/source/objectinstance.h index 5911dae5..3dc5da6a 100644 --- a/source/objectinstance.h +++ b/source/objectinstance.h @@ -11,9 +11,12 @@ class Object; 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 { diff --git a/source/pipeline.h b/source/pipeline.h index d39bce5a..f8fdb545 100644 --- a/source/pipeline.h +++ b/source/pipeline.h @@ -17,6 +17,28 @@ class DepthTest; 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: diff --git a/source/postprocessor.h b/source/postprocessor.h index d9489de2..0666dd46 100644 --- a/source/postprocessor.h +++ b/source/postprocessor.h @@ -24,10 +24,10 @@ public: 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. diff --git a/source/programdata.cpp b/source/programdata.cpp index b8a272c0..7334596c 100644 --- 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()) { + /* 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; diff --git a/source/programdata.h b/source/programdata.h index cf642e61..38803c57 100644 --- a/source/programdata.h +++ b/source/programdata.h @@ -17,7 +17,13 @@ class Vector3; 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 { @@ -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; + 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; }; diff --git a/source/renderable.h b/source/renderable.h index 78879a3d..2342ae28 100644 --- 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. + +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 { @@ -20,10 +23,17 @@ 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; } + /** 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; + + /** 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; }; diff --git a/source/renderer.h b/source/renderer.h index 501d1db3..dd54ca16 100644 --- 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 -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: @@ -92,7 +94,9 @@ public: 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 &); diff --git a/source/tag.h b/source/tag.h index ac31bce6..28b4fa01 100644 --- a/source/tag.h +++ b/source/tag.h @@ -6,6 +6,10 @@ 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; diff --git a/source/uniformblock.h b/source/uniformblock.h index 12b24de3..1a277106 100644 --- a/source/uniformblock.h +++ b/source/uniformblock.h @@ -16,6 +16,10 @@ class Uniform; class Vector3; class Vector4; +/** +Stores uniforms with a specific layout. Both named and default uniform blocks +are supported. +*/ class UniformBlock: public Bufferable { private: