From: Mikko Rasa Date: Fri, 16 May 2014 18:35:30 +0000 (+0300) Subject: Improve interface documentation a bit X-Git-Url: http://git.tdb.fi/?p=libs%2Fgl.git;a=commitdiff_plain;h=a1eb8711ba225bb4423868c50369ad5592465171 Improve interface documentation a bit --- diff --git a/source/colorcurve.h b/source/colorcurve.h index 75e7fd30..f66ff976 100644 --- a/source/colorcurve.h +++ b/source/colorcurve.h @@ -14,7 +14,9 @@ Processes oversaturated colors to preserve hues. When one color component exceeds 1.0, the others are scaled towards white. A transition curve is also applied near 1.0 to prevent the abrupt change in the gradient. -Only makes sense when used in an HDR framebuffer. +Gamma or sRGB correction can also be applied to the output. It can be used to +improve color reproduction by performing lighting calculations in linear color +space and converting to sRGB for display. */ class ColorCurve: public PostProcessor { @@ -35,8 +37,15 @@ public: saturated value. */ void set_brightness(float); + /** Sets the gamma value used for mapping output colors. Allowed range is + from 0.1 to 10. */ void set_gamma(float); + + /** Sets output mapping to sRGB. This is almost, but not exactly equivalent + to set_gamma(2.2). */ void set_srgb(); + + /// Sets output mapping to linear. This is equivalent to set_gamma(1). void set_linear(); virtual void render(const Texture2D &, const Texture2D &); diff --git a/source/font.h b/source/font.h index fea97a11..bb8bd0a2 100644 --- a/source/font.h +++ b/source/font.h @@ -13,6 +13,9 @@ namespace GL { class PrimitiveBuilder; class Texture2D; +/** +Stores a set of glyphs and creates strings out of them. +*/ class Font { public: @@ -66,12 +69,21 @@ public: void set_texture(const Texture2D &); const Texture2D &get_texture() const; + + /** Adds a glyph to the font. There must not be an existing glyph with the + same code. */ void add_glyph(const Glyph &); void set_kerning(unsigned, unsigned, float); + + /** Returns the size used to generate the font texture. This serves as a + hint for obtaining the best quality when rendering strings. */ float get_native_size() const { return native_size; } + float get_ascent() const { return ascent; } float get_descent() const { return descent; } + /** Returns the width of a string, in multiples of the font size. Scale the + result according to the size used in rendering. */ float get_string_width(const std::string &, StringCodec::Decoder &) const; template @@ -84,7 +96,8 @@ public: float get_string_width(const std::string &str) const { return get_string_width(str); } - /// Draws a string to the framebuffer with Immediate. + /** Draws a string to the framebuffer with Immediate. It is drawn with size + 1.0; set up matrices for the desired size before the call. */ void draw_string(const std::string &, StringCodec::Decoder &, const Color & = Color()) const; template @@ -97,10 +110,10 @@ public: void draw_string(const std::string &str, const Color &color = Color()) const { draw_string(str, color); } - /** Builds the primitives for a string. The PrimitiveBuilder should be - associated with a target that has at least VERTEX2 and TEXCOORD2 components. - The texture is not bound, to avoid unnecessary bindings when creating - meshes. */ + /** Builds the primitives for a string. Two-dimensional vertex and texture + coordinates are generated. Size 1.0 is used for building; set up the + builder's matrix before the call. The texture is not bound, to avoid + unnecessary bindings when creating meshes. */ void build_string(const std::string &, StringCodec::Decoder &, PrimitiveBuilder &) const; template diff --git a/source/program.cpp b/source/program.cpp index baeba9f5..66ca36b1 100644 --- a/source/program.cpp +++ b/source/program.cpp @@ -125,7 +125,7 @@ void Program::link() if(len && strncmp(name, "gl_", 3)) { /* Some implementations report the first element of a uniform array, - others report just the name of an array. */ + others report just the name of the array itself. */ if(len>3 && !strcmp(name+len-3, "[0]")) name[len-3] = 0; diff --git a/source/program.h b/source/program.h index b41f9ac2..e78c8ccd 100644 --- a/source/program.h +++ b/source/program.h @@ -14,6 +14,10 @@ namespace GL { class Shader; +/** +A complete shader program. Programs can be assembled of individual Shaders or +generated with a set of standard features. +*/ class Program: public Bindable { public: @@ -68,9 +72,15 @@ private: bool legacy_vars; public: + /// Constructs an empty Program with no Shaders attached. Program(); + + /// Constructs a Program with standard features. Program(const ProgramBuilder::StandardFeatures &); + + /// Constructs a Program from vertex and fragment shader source code. Program(const std::string &, const std::string &); + private: void init(); public: diff --git a/source/programbuilder.cpp b/source/programbuilder.cpp index f22d1088..26689bce 100644 --- a/source/programbuilder.cpp +++ b/source/programbuilder.cpp @@ -38,7 +38,7 @@ Naming conventions: color_* Color with rgba components */ -/* The array are stored in reverse order, so that variables always come after +/* The array is stored in reverse order, so that variables always come after anything that might need them. */ const ProgramBuilder::VariableDefinition ProgramBuilder::standard_variables[] = { diff --git a/source/programbuilder.h b/source/programbuilder.h index cca0c149..678ee2ca 100644 --- a/source/programbuilder.h +++ b/source/programbuilder.h @@ -18,9 +18,15 @@ public: virtual ~invalid_variable_definition() throw() { } }; +/** +Generates shaders with common features. +*/ class ProgramBuilder { public: + /** + Describes the features of a standard shader program. + */ struct StandardFeatures { class Loader: public DataFile::ObjectLoader diff --git a/source/renderable.h b/source/renderable.h index eae75cce..9a534e90 100644 --- a/source/renderable.h +++ b/source/renderable.h @@ -50,12 +50,12 @@ public: /** Called when a complete frame has been rendered. */ virtual void finish_frame() const { } - /** Renders the renderable without a renderer. This can be convenient in + /** 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 + /** 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/resources.h b/source/resources.h index 0390d859..51adec4a 100644 --- a/source/resources.h +++ b/source/resources.h @@ -9,6 +9,10 @@ namespace GL { class Texture2D; +/** +A collection class for GL resources. Most useful as a base class for an +application-specific collection. +*/ class Resources: virtual public DataFile::Collection { private: diff --git a/source/shader.h b/source/shader.h index 63af9b3a..961cb694 100644 --- a/source/shader.h +++ b/source/shader.h @@ -7,6 +7,12 @@ namespace Msp { namespace GL { +/** +A single shader stage. Shaders must be attached to a Program to be used. + +This class can't be instantiated directly. Use one of the VertexShader and +FragmentShader classes to create Shaders. +*/ class Shader { private: diff --git a/source/technique.h b/source/technique.h index d1fab38f..141fa9c8 100644 --- a/source/technique.h +++ b/source/technique.h @@ -11,6 +11,7 @@ class Material; class Texture; /** +Ties multiple tagged render passes together. */ class Technique { diff --git a/source/texture2d.h b/source/texture2d.h index dce58a78..639d47a6 100644 --- a/source/texture2d.h +++ b/source/texture2d.h @@ -12,8 +12,8 @@ namespace GL { /** Two-dimensional texture. Consists of an array of texels in the shape of a -rectangle. Texture coordinate have a principal range of [0, 1]. This is the -most common type of texture. +rectangle. Texture coordinate have a range of [0, 1]. Coordinates outside of +this range are subject to wrapping. This is the most common type of texture. */ class Texture2D: public Texture { @@ -60,14 +60,15 @@ public: void sub_image(unsigned level, int x, int y, unsigned wd, unsigned ht, PixelFormat fmt, DataType type, const void *data); - /** Loads an image from a file and uploads it to the texture. If storage - has not been defined, it will be set to match the loaded image. Otherwise - the image must be compatible with the defined storage. */ + /// Loads a Graphics::Image from a file and uploads it to the texture. void load_image(const std::string &fn, bool srgb = false); /** Uploads an image to the texture. If storage has not been defined, it will be set to match the image. Otherwise the image must be compatible with - the defined storage. */ + the defined storage. + + If srgb is true and storage is determined by this call, then an sRGB pixel + format will be used. */ void image(const Graphics::Image &, bool srgb = false); unsigned get_width() const { return width; } diff --git a/source/texunit.h b/source/texunit.h index 05952a22..8962e638 100644 --- a/source/texunit.h +++ b/source/texunit.h @@ -10,6 +10,9 @@ class TexEnv; class TexGen; class Texture; +/** +Keeps track of texture unit related state. Mostly for internal use. +*/ class TexUnit { private: