namespace GL {
/**
-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.
+Base class for textures. Most operations are defined in subclasses.
-A texture can consinst of a stack of images, called a mipmap. The dimensions
-of each mipmap level are half that of the previous level. The mipmap stack
-can be used for texture minification; see the Sampler class for details.
+Memory must be allocated for the texture by calling storage(). Each subclass
+provides this function with parameters appropriate to that type of texture.
+Contents can then be modified using the image() and sub_image() functions
+provided by subclasses.
+
+Most types of textures can consist of a pyramid of images, called a mipmap.
+The dimensions of each mipmap level are half that of the previous level.
+
+Textures can be used as either a data source or target for draw commands. To
+read from a texture in a shader, it must be paired with a Sampler to determine
+how the texels are accessed. To draw into a texture, it must be attached to a
+Framebuffer.
*/
class Texture: public TextureBackend, public Resource
{
using TextureBackend::generate_mipmap;
- /// Loads a Graphics::Image from a file and uploads it to the texture.
+ /** Loads an image into the texture from a file. */
virtual void load_image(const std::string &, unsigned = 0);
- /** 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. Semantics depend on the type of texture. */
+ /** Sets the texture's contents from an image. 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. Subclasses may impose restrictions
+ on the image's dimensions. */
virtual void image(const Graphics::Image &, unsigned = 0) = 0;
- virtual std::uint64_t get_data_size() const { return 0; }
+ virtual std::size_t get_data_size() const { return 0; }
using TextureBackend::set_debug_name;