Update and improve documentation

[libs/gl.git] / source / core / texture3d.h

diff --git a/source/core/texture3d.h b/source/core/texture3d.h
index d791633d3a306ef08607016efe4b956d850f43fa..9d5104c91e42892de2d9189b31291f4352c98e2f 100644 (file)
--- a/source/core/texture3d.h
+++ b/source/core/texture3d.h
@@ -9,8 +9,7 @@ namespace Msp {
 namespace GL {
 
 /**
-Three-dimensional texture.  Consists of an array of texels in the shape of a
-right cuboid.  Texture coordinates have a principal range of [0, 1].
+Three-dimensional texture, consisting of a cuboid-shaped array of texels.
 */
 class Texture3D: public Texture3DBackend
 {
@@ -40,28 +39,25 @@ protected:
 public:
        Texture3D() = default;
 
-       /** Defines storage structure for the texture.  If lv is zero, the number
-       of mipmap levels is automatically determined from storage dimensions.
-
-       Must be called before an image can be uploaded.  Once storage is defined,
-       it can't be changed. */
-       void storage(PixelFormat fmt, unsigned wd, unsigned ht, unsigned dp, unsigned lv = 0);
-
-       /** Updates the contents of the entire texture.  Storage must be defined
-       beforehand.  The image data must have dimensions and format matching the
-       defined storage. */
-       void image(unsigned level, const void *data);
-
-       /** Updates a cuboid-shaped region of the texture.  Storage must be defined
-       beforehand.  The image data must be in a format mathing the defined storage
-       and the update region must be fully inside the texture. */
-       void sub_image(unsigned level, int x, int y, int z, unsigned wd, unsigned ht, unsigned dp, const void *data);
-
-       /** Updates the contents of the entire texture from an image.  If storage
-       has not been defined, it will be set to match the image.  In this case the
-       image will be treated as a stack of square layers and its height must be
-       divisible by its width.  Otherwise the image must match the defined
-       storage. */
+       /** Sets storage format and dimensions and allocates memory for the texture.
+       If lv is zero, a complete mipmap pyramid is automatically created.  Storage
+       cannot be changed once set. */
+       void storage(PixelFormat, unsigned wd, unsigned ht, unsigned dp, unsigned lv = 0);
+
+       /** Replaces contents of an entire mipmap level.  Allocated storage must
+       exist.  The image data is interpreted according to the storage format and
+       must have size matching the selected mipmap level. */
+       void image(unsigned level, const void *);
+
+       /** Replaces a cuboid-shaped region of the texture.  Allocated storage must
+       exist.  The image data is interpreted according to the storage format and
+       the region must be fully inside the texture. */
+       void sub_image(unsigned level, int x, int y, int z, unsigned wd, unsigned ht, unsigned dp, const void *);
+
+       /** Sets the texture's contents from an image.  The image is treated as a
+       stack of square layers and its height must be divisible by its width.  If
+       storage has not been allocated yet, it will be set to match the image.
+       Otherwise the image must be compatible with the existing storage. */
        virtual void image(const Graphics::Image &, unsigned = 0);
 
        unsigned get_width() const { return width; }