X-Git-Url: http://git.tdb.fi/?p=libs%2Fgl.git;a=blobdiff_plain;f=source%2Fcore%2Ftexture3d.h;h=9d5104c91e42892de2d9189b31291f4352c98e2f;hp=d791633d3a306ef08607016efe4b956d850f43fa;hb=190a7e11237351f6b730c28f7b16f183e8adc69c;hpb=be6ffe96ecb4707599fe1a6f620c348760213d46

diff --git a/source/core/texture3d.h b/source/core/texture3d.h
index d791633d..9d5104c9 100644
--- 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; }