Comment updates for texture and framebuffer classes.

[libs/gl.git] / source / texture.h

diff --git a/source/texture.h b/source/texture.h
index 580517257e5ffc844808aea112d465929a5d2519..30ad484cbc29835108788add581d54ad48791fd1 100644 (file)
--- a/source/texture.h
+++ b/source/texture.h
@@ -10,19 +10,35 @@ namespace GL {
 
 enum TextureFilter
 {
-       NEAREST                = GL_NEAREST,
-       LINEAR                 = GL_LINEAR,
+       /// No filtering
+       NEAREST = GL_NEAREST,
+
+       /// Bilinear filtering
+       LINEAR = GL_LINEAR,
+
+       /// Mipmapping without filtering
        NEAREST_MIPMAP_NEAREST = GL_NEAREST_MIPMAP_NEAREST,
-       NEAREST_MIPMAP_LINEAR  = GL_NEAREST_MIPMAP_LINEAR,
-       LINEAR_MIPMAP_NEAREST  = GL_LINEAR_MIPMAP_NEAREST,
-       LINEAR_MIPMAP_LINEAR   = GL_LINEAR_MIPMAP_LINEAR
+
+       /// Linear filtering between two mipmap levels
+       NEAREST_MIPMAP_LINEAR = GL_NEAREST_MIPMAP_LINEAR,
+
+       /// Bilinear filtering on the closest mipmap level
+       LINEAR_MIPMAP_NEAREST = GL_LINEAR_MIPMAP_NEAREST,
+
+       /// Trilinear filtering between two mipmap levels
+       LINEAR_MIPMAP_LINEAR = GL_LINEAR_MIPMAP_LINEAR
 };
 
 
 enum TextureWrap
 {
-       REPEAT          = GL_REPEAT,
-       CLAMP_TO_EDGE   = GL_CLAMP_TO_EDGE,
+       /// Tile the texture infinitely
+       REPEAT = GL_REPEAT,
+
+       /// Extend the texels at the edge of the texture to infinity
+       CLAMP_TO_EDGE = GL_CLAMP_TO_EDGE,
+
+       /// Tile the texture, with every other repetition mirrored
        MIRRORED_REPEAT = GL_MIRRORED_REPEAT
 };
 
@@ -31,6 +47,21 @@ enum TextureWrap
 Base class for textures.  This class only defines operations common for all
 texture types and is not instantiable.  For specifying images for textures, see
 one of the dimensioned texture classes.
+
+A texture is generally rendered at a size that's either smaller or larger than
+its native size, so that the texture coordinates do not exactly correspond to
+the texels of the texture.  The kind of filtering used, if any, is determined
+by the minification and magnification filter parameters.  The default is LINEAR
+for magnification and NEAREST_MIPMAP_LINEAR for minification.
+
+When a mipmapped filter is in use, the texture consists of a stack of mipmap
+images.  Level 0 is the base image.  Each level above 0 has half the size of
+the previous level, rounded down and clamped to 1.  The level with size 1 in
+all dimensions is the last mipmap level.  All levels must be allocated for the
+texture to be usable.
+
+If texture coordinates fall outside of the principal range of the texture,
+wrapping is applied.  The default for all directions is REPEAT.
 */
 class Texture
 {
@@ -83,13 +114,27 @@ protected:
 public:
        void set_min_filter(TextureFilter);
        void set_mag_filter(TextureFilter);
+
+       /** Sets the wrapping mode for all coordinates. */
        void set_wrap(TextureWrap);
+
        void set_wrap_s(TextureWrap);
        void set_wrap_t(TextureWrap);
        void set_wrap_r(TextureWrap);
+
+       /** Sets automatic mipmap generation.  If enabled, mipmaps are generated
+       when a texture image is uploaded. */
        void set_generate_mipmap(bool);
+
+       /** Sets depth texture comparison.  Has no effect on other formats.  When
+       comparison is enabled, the third component of the texture coordinate is
+       compared against the texel value, and the result is returned as the texture
+       sample. */
        void set_compare_enabled(bool);
+
+       /** Sets the function to use for depth comparison. */
        void set_compare_func(Predicate);
+
        GLenum get_target() const { return target; }
        unsigned get_id() const { return id; }