[−][src]Module web_glitz::image
This module provides data types and traits for the allocation and manipulation of GPU-accessible image data.
The [format] module defines a number of types that implement [InternalFormat]; these types represent the available data formats for image storage.
A distinction is made between a texture ([Texture2D], [Texture3D], [Texture2DArray], [TextureCube]) and a renderbuffer ([Renderbuffer]): a texture may be sampled (see sampler), but is not necessarily optimized for use with a RenderTarget, whereas a renderbuffer may not be sampled, but is optimized for use with a RenderTarget.
2-Dimensional image storage
2-Dimensional image storage has a width
and a height
. It may be thought of as a width
by
height
2-dimensional grid of cells, where each cell stores a pixel value; all pixels share a
type determined by the storage's [InternalFormat].
The [Texture2D] and [Renderbuffer] types provide 2-dimensional image storage. An Image2DSource may hold data that is to be uploaded to 2-dimensional image storage.
Multisampling
Multisampling is an anti-aliasing technique where instead of a single value, multiple sample values are stored for each pixel from which a final anti-aliased pixel value may be derived. Multisample formats may be constucted with [Multisample]. Multisample storage formats are currently only supported for [Renderbuffer]s, see [RenderingContext::try_create_multisample_renderbuffer] for details.
Layered image storage
Layered image storage (also 3-dimensional image storage) has a width
, a height
and depth
.
It may be thought of as a width
by height
by depth
3-dimensional grid of cells, where each
cell stores one value; all values share a type determined by the storage's [InternalFormat]. It
may alternatively be thought of as layered 2-dimensional image storage, where there are depth
layers of 2-dimensional images of size width
by height
.
The [Texture2DArray] and [Texture3D] types provide layered image storage. A LayeredImageSource may hold data that is to be uploaded to layered image storage. Alternatively, an Image2DSource may hold data that is to be uploaded to an individual layer of a layered image.
Cube map storage
Cube map storage stores 6 2-dimensional images (one for each face of a cube) of the same size
(all six images share the same width
, and all 6 images share the same height
) and the same
[InternalFormat]. The six images in cube map storage are also referred to as its "faces",
specifically they are:
- The "positive x" face.
- The "negative x" face.
- The "positive y" face.
- The "negative y" face.
- The "positive z" face.
- The "negative z" face.
The [TextureCube] type provides cube map storage. An Image2DSource may hold data that is to be uploaded to an individual face.
Mipmapping
Texture storage ([Texture2D], [Texture3D], [Texture2DArray], [TextureCube]) does not store just
base images, it stores partial or complete mipmap chains. A mipmap chain consists of a series
of (2-dimensional or layered) images, starting with a base image with a predetermined width and
height. Each subsequent image in the chain is half the width and half the height of the previous
image in the chain, rounded down to the nearest integer. The chain is complete when either the
width or the height reaches 1
. The images in the mipmap chain are also called the "levels" of
the mipmap and they are numbered incrementally, starting at 0
. For example, a 256
by 128
2 dimensional image has the following complete mipmap chain:
- Level
0
: width256
, height128
. - Level
1
: width128
, height64
. - Level
2
: width64
, height32
. - Level
3
: width32
, height16
. - Level
4
: width16
, height8
. - Level
5
: width8
, height4
. - Level
6
: width4
, height2
. - Level
7
: width2
, height1
.
The chain stops at level 7
, when the height reaches 1
, for a total of 8 levels. Level 0 is
also called the "base level".
Texture storage does not necessarily have to store a complete mipmap chain, it may only store
the first N
levels, where N
is smaller than the number of levels in the complete mipmap
chain for the image. N
must be at least 1
; a texture must have at least a base level.
The main application for mipmapping is minification filtering, in which case each level in the chain is typically obtained by linear minification filtering of the preceding level (see [MinificationFilter] for details). If the texture format implements [Filterable], then the image data for such a chain can be generated from the base level by the driver (see [Texture2D::generate_mipmap], [Texture3D::generate_mipmap], [Texture2DArray::generate_mipmap], [TextureCube::generate_mipmap]).
Modules
format | Provides marker types for various internal image storage formats. |
renderbuffer | |
sampler | |
texture_2d | |
texture_2d_array | |
texture_3d | |
texture_cube |
Structs
Image2DSource | Encapsulates data that may be uploaded to a 2D texture (sub-)image. |
LayeredImageSource | Encapsulates data that may be uploaded to a layered texture (sub-)image. |
MaxMipmapLevelsExceeded | Error returned when creating a texture using MipmapLevels::Partial to specify a specific number of mipmap levels, but the number of levels specified is greater than the number of levels in the complete mipmap chain for an image of the relevant dimensions. |
Enums
FromPixelsError | Error returned by Image2DSource::from_pixels or [Image3DSource::from_pixels]. |
MipmapLevels | Describes the number of mipmap levels that are to be allocated for a texture. |
Region2D | Represents a region of a 2-dimensional image. |
Region3D | Represents a region of a 3-dimensional (layered) image. |