From: Mikko Rasa Date: Mon, 20 Oct 2014 09:28:59 +0000 (+0300) Subject: Improve documentation for a number of classes X-Git-Url: http://git.tdb.fi/?p=libs%2Fgl.git;a=commitdiff_plain;h=c51030d1cb2308d30db80303a561de1774dfdb76 Improve documentation for a number of classes --- diff --git a/gl.fixes.xml b/gl.fixes.xml index c6459cf3..d805cfbc 100644 --- a/gl.fixes.xml +++ b/gl.fixes.xml @@ -81,7 +81,7 @@ - diff --git a/source/light.h b/source/light.h index fa5bf287..ee62ce35 100644 --- a/source/light.h +++ b/source/light.h @@ -11,6 +11,11 @@ namespace GL { class Matrix; class ProgramData; +/** +Stores properties of a single light source. + +Lights do not cast shadows by themselves. See ShadowMap for that. +*/ class Light { private: @@ -41,13 +46,23 @@ private: void update_parameter(int, int = -1) const; public: + /** Sets the diffuse (direction-independent) color of the Light. Provided + to shaders with the name light_sources[i].diffuse. */ void set_diffuse(const Color &c); + + /** Sets the specular (direction-dependent) color of the Light. Provided to + shaders with the name light_sources[i].diffuse. */ void set_specular(const Color &c); + const Color &get_diffuse() const { return diffuse; } const Color &get_specular() const { return specular; } + /** Sets the position of the Light. For a directional light, set the xyz + components to a vector pointing towards the light and the w component to 0. */ void set_position(const Vector4 &); + const Vector4 &get_position() const { return position; } + void set_spot_direction(const Vector3 &); void set_spot_exponent(float); void set_spot_cutoff(float); @@ -57,7 +72,10 @@ public: void set_attenuation(float, float, float); const float *get_attenuation() const { return attenuation; } + /** Updates a ProgramData object with the uniforms for the Light. A view + matrix and light source index must be passed in. */ void update_shader_data(ProgramData &, const Matrix &, unsigned) const; + void bind() const { return bind_to(0); } void bind_to(unsigned) const; diff --git a/source/lighting.h b/source/lighting.h index 063bbf2b..5469cef5 100644 --- a/source/lighting.h +++ b/source/lighting.h @@ -14,7 +14,8 @@ namespace GL { class Light; /** -Encapsulates global lighting parameters and a number of individual lights. +Encapsulates global lighting parameters and any number of individual light +sources. */ class Lighting: public Bindable { @@ -28,17 +29,33 @@ private: public: Lighting(); + /** Sets the ambient lighting color. Affects all surfaces in the scene. */ void set_ambient(const Color &); + const Color &get_ambient() const { return ambient; } + /** Sets the color of the sky at zenith. Has no effect without shaders. */ void set_sky_color(const Color &); + + /** Sets the direction of the sky. Defaults to positive Z axis. Has no + effect without shaders. */ void set_sky_direction(const Vector3 &); + + /** Sets the angle where skylight cuts off, counted from the true horizon. + Has no effect without shaders. */ void set_horizon_angle(const Geometry::Angle &); + /** Attaches a light source. If the attachment index is greater than + LightUnit::get_n_units, the Lighting can't be bound for legacy mode. */ void attach(unsigned, const Light &); + + /** Detaches a light source. */ void detach(unsigned); + /** Updates a ProgramData object with the uniforms for the Lighting, + including all attached light sources. A view matrix must be passed in. */ void update_shader_data(ProgramData &, const Matrix &) const; + void bind() const; static void unbind(); diff --git a/source/material.h b/source/material.h index a149f6d4..e1bfec4c 100644 --- a/source/material.h +++ b/source/material.h @@ -10,8 +10,15 @@ namespace Msp { namespace GL { /** -Stores OpenGL material properties. Since OpenGL does not support material -objects, application of material is done with several calls to glMaterial. +Stores basic material properties. This includes color and reflection +parameters, but does not include texturing. Materials interact with light +soucres and ambient lighting to produce the base color of a surface. Textures +can be used to add detail. + +Material provides a set of uniform variables for use with shaders. Standard +shaders generated by ProgramBuilder only use it when legacy mode is disabled. + +In legacy mode, materials are applied with several calls to glMaterial. */ class Material: public BindableWithDefault { @@ -61,19 +68,38 @@ private: void update_parameter(int) const; public: - void set_ambient(const Color &a); - void set_diffuse(const Color &d); - void set_specular(const Color &s); - void set_emission(const Color &e); - void set_shininess(float s); + /** Sets the ambient color of the material. Provided to shaders with the + name material.ambient. */ + void set_ambient(const Color &); + + /** Sets the diffuse (direction-independent) color of the material. + Provided to shaders with the name material.diffuse. */ + void set_diffuse(const Color &); + + /** Sets the specular (direction-dependent) color of the material. Provided + to shaders with the name material.specular. */ + void set_specular(const Color &); + void set_emission(const Color &); + + /** Sets the specular exponent of the material. Provided to shaders with + the name material.shininess. */ + void set_shininess(float); + + /** Sets the reflectivity of the material. Provided to shaders with the + name reflectivity. Has no effect when shaders are not used. */ void set_reflectivity(float); + const Color &get_ambient() const { return ambient; } const Color &get_diffuse() const { return diffuse; } const Color &get_specular() const { return specular; } const Color &get_emission() const { return emission; } float get_shininess() const { return shininess; } float get_reflectivity() const { return reflectivity; } + + /** Returns the uniforms for the material. Not needed for shaders that use + the legacy built-in uniform gl_FrontMaterial and have no reflections. */ const ProgramData &get_shader_data() const { return shdata; } + void bind() const; }; diff --git a/source/mesh.h b/source/mesh.h index 14cb072d..388d4d88 100644 --- a/source/mesh.h +++ b/source/mesh.h @@ -89,6 +89,8 @@ public: void draw() const; void draw(Renderer &) const; + /** Binds the mesh for rendering. The vertex array is applied using generic + attributes only. Uses vertex array object if possible. */ void bind() const; static void unbind(); diff --git a/source/programbuilder.h b/source/programbuilder.h index 62d8e07a..43d43fcc 100644 --- a/source/programbuilder.h +++ b/source/programbuilder.h @@ -20,12 +20,43 @@ public: /** Generates shaders with common features. + +The shader generation model is based on variable substitutions. Initially, a +goal variable is given for each shader stage. The expression for computing +each variable is examined for further variable definitions. When there are no +more known variables available for substitution, the process terminates. Any +unknown variables at this point are assumed to be provided by OpenGL. + +Variables can be defined in a number of scopes. The scope of a variable +determines where its value is computed. If a variable is referenced from a +scope that comes after the declaration scope, an interface variable is +automatically emitted. + +Generated shaders are normally optimized by inlining variables with a single +reference into the expression referencing them. This can result in expressions +of several hundreds of characters in length, so optimizations can be disabled +with the set_optimize() method for debugging purposes. + +Custom variables can be injected to the generated shaders with the custom +member of the StandardFeatures struct. The syntax is: + + := [ ...] + := [= ] ; + := uniform | attribute | vertex | fragment + := (any GLSL type) + := (valid identifier) + := (GLSL expression) + +The custom variables should always include at least one override for a built-in +variable; otherwise they will be ignored as no built-in expression references +them. */ class ProgramBuilder { public: /** - Describes the features of a standard shader program. + Describes the features of a standard shader program. All boolean features + default to false unless stated otherwise. */ struct StandardFeatures { @@ -35,16 +66,41 @@ public: Loader(StandardFeatures &); }; + /** Use a diffuse map texture. */ bool texture; + + /** Use material properties if lighting is true, or vertex colors if + lighting is false. */ bool material; + + /** Use lighting to compute the brightness of surfaces. */ bool lighting; + + /** Number of lights to use in lighting calculations. Defaults to 1. */ unsigned max_lights; + + /** Use a skylight component for ambient lighting. */ bool skylight; + + /** Use a specular lighting component. */ bool specular; + + /** Use a normal map texture. Only used if lighting is true. */ bool normalmap; + + /** Use a shadow map. Requires a ShadowMap effect or equivalent in the + pipeline. */ bool shadow; + + /** Use a reflection cube map. Requires an EnvironmentMap effect or + equivalend in the pipeline. */ bool reflection; + + /** Force the use of legacy shaders conforming to GLSL 1.10. Defaults + to true if the version of GLSL is less than 1.30, false otherwise. */ bool legacy; + + /** Custom variables to use in the shader. */ std::string custom; StandardFeatures(); @@ -137,9 +193,15 @@ private: public: ProgramBuilder(const StandardFeatures &); + /// Enable or disable optimization. Defaults to enabled. void set_optimize(bool); + + /// Create a new Program with the features associated with the builder. Program *create_program() const; + + /// Generate shaders and add them to an existing program. void add_shaders(Program &) const; + private: std::string create_source(const std::list &, VariableScope) const; bool evaluate_flags(const char *) const; diff --git a/source/vertexarray.h b/source/vertexarray.h index d6dee7dd..bf118eee 100644 --- a/source/vertexarray.h +++ b/source/vertexarray.h @@ -17,6 +17,17 @@ namespace GL { class Buffer; +/** +Stores vertex data. Both legacy and generic attributes are supported. Mixing +the two is possible but discouraged, as driver-specific issues may arise. + +The array's contents can be modified with the append and modify methods. To +obtain the location of an individual component within the vertex, use +VertexFormat::offset. + +A higher-level interface for filling in vertex data is available in the +VertexArrayBuilder class. +*/ class VertexArray: public Bindable, public Bufferable { public: @@ -49,7 +60,9 @@ public: VertexArray(const VertexFormat &); ~VertexArray(); + /// Resets the VertexArray to a different format. All data is cleared. void reset(const VertexFormat &); + const VertexFormat &get_format() const { return format; } private: static unsigned get_array_slot(unsigned char); @@ -58,9 +71,16 @@ public: /// Deprecated alias for use_buffer void use_vertex_buffer(Buffer *b) { use_buffer(b); } + /// Clears all vertices from the array. void clear(); + + /// Reserve space for vertices. void reserve(unsigned); + + /// Append a new vertex at the end of the array and return its location. float *append(); + + /// Returns the location of a vertex for modification. float *modify(unsigned); private: virtual unsigned get_data_size() const; @@ -71,8 +91,15 @@ public: const std::vector &get_data() const { return data; } const float *operator[](unsigned i) const { return &data[0]+i*stride; } + /** Equivalent to apply(true). For compatibility with the Bindable + interface. */ void bind() const { apply(); } - void apply(bool = true) const; + + /** Applies component arrays to the GL. If legacy is true, they are applied + as is. If legacy is false, any legacy attributes are converted to generic + attributes. */ + void apply(bool legacy = true) const; + private: static void apply_arrays(const std::vector *, const std::vector *, const float *, unsigned, bool); public: