Texture Format#
Description#
The format of a texture can be described by the dtype
parameter
during texture creation. For example the moderngl.Context.texture()
.
The default dtype
is f1
. Each component is an unsigned byte (0-255)
that is normalized when read in a shader into a value from 0.0 to 1.0.
The formats are based on the string formats used in numpy.
Some quick example of texture creation:
# RGBA (4 component) f1 texture
texture = ctx.texture((100, 100), 4) # dtype f1 is default
# R (1 component) f4 texture (32 bit float)
texture = ctx.texture((100, 100), 1, dype="f4")
# RG (2 component) u2 texture (16 bit unsigned integer)
texture = ctx.texture((100, 100), 2, dtype="u2")
Texture contents can be passed in using the data
parameter during
creation or by using the write()
method. The object passed in
data
can be bytes or any object supporting the buffer protocol.
When writing data to texture the data type can be derived from
the internal format in the tables below. f1
textures takes
unsigned bytes (u1
or numpy.uint8
in numpy) while
f2
textures takes 16 bit floats (f2
or numpy.float16
in numpy).
Float Textures#
f1
textures are just unsigned bytes (8 bits per component) (GL_UNSIGNED_BYTE
)
The f1
texture is the most commonly used textures in OpenGL
and is currently the default. Each component takes 1 byte (4 bytes for RGBA).
This is not really a “real” float format, but a shader will read
normalized values from these textures. 0-255
(byte range) is read
as a value from 0.0
to 1.0
in shaders.
In shaders the sampler type should be sampler2D
, sampler2DArray
sampler3D
, samplerCube
etc.
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
f1 |
1 |
GL_RED |
GL_R8 |
f1 |
2 |
GL_RG |
GL_RG8 |
f1 |
3 |
GL_RGB |
GL_RGB8 |
f1 |
4 |
GL_RGBA |
GL_RGBA8 |
f2
textures stores 16 bit float values (GL_HALF_FLOAT
).
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
f2 |
1 |
GL_RED |
GL_R16F |
f2 |
2 |
GL_RG |
GL_RG16F |
f2 |
3 |
GL_RGB |
GL_RGB16F |
f2 |
4 |
GL_RGBA |
GL_RGBA16F |
f4
textures store 32 bit float values. (GL_FLOAT
)
Note that some drivers do not like 3 components because of alignment.
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
f4 |
1 |
GL_RED |
GL_R32F |
f4 |
2 |
GL_RG |
GL_RG32F |
f4 |
3 |
GL_RGB |
GL_RGB32F |
f4 |
4 |
GL_RGBA |
GL_RGBA32F |
Integer Textures#
Integer textures come in a signed and unsigned version. The advantage
with integer textures is that shader can read the raw integer values
from them using for example usampler*
(unsigned) or isampler*
(signed).
Integer textures do not support LINEAR
filtering (only NEAREST
).
Unsigned#
u1
textures store unsigned byte values (GL_UNSIGNED_BYTE
).
In shaders the sampler type should be usampler2D
, usampler2DArray
usampler3D
, usamplerCube
etc.
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
u1 |
1 |
GL_RED_INTEGER |
GL_R8UI |
u1 |
2 |
GL_RG_INTEGER |
GL_RG8UI |
u1 |
3 |
GL_RGB_INTEGER |
GL_RGB8UI |
u1 |
4 |
GL_RGBA_INTEGER |
GL_RGBA8UI |
u2
textures store 16 bit unsigned integers (GL_UNSIGNED_SHORT
).
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
u2 |
1 |
GL_RED_INTEGER |
GL_R16UI |
u2 |
2 |
GL_RG_INTEGER |
GL_RG16UI |
u2 |
3 |
GL_RGB_INTEGER |
GL_RGB16UI |
u2 |
4 |
GL_RGBA_INTEGER |
GL_RGBA16UI |
u4
textures store 32 bit unsigned integers (GL_UNSIGNED_INT
)
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
u4 |
1 |
GL_RED_INTEGER |
GL_R32UI |
u4 |
2 |
GL_RG_INTEGER |
GL_RG32UI |
u4 |
3 |
GL_RGB_INTEGER |
GL_RGB32UI |
u4 |
4 |
GL_RGBA_INTEGER |
GL_RGBA32UI |
Signed#
i1
textures store signed byte values (GL_BYTE
).
In shaders the sampler type should be isampler2D
, isampler2DArray
isampler3D
, isamplerCube
etc.
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
i1 |
1 |
GL_RED_INTEGER |
GL_R8I |
i1 |
2 |
GL_RG_INTEGER |
GL_RG8I |
i1 |
3 |
GL_RGB_INTEGER |
GL_RGB8I |
i1 |
4 |
GL_RGBA_INTEGER |
GL_RGBA8I |
i2
textures store 16 bit integers (GL_SHORT
).
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
i2 |
1 |
GL_RED_INTEGER |
GL_R16I |
i2 |
2 |
GL_RG_INTEGER |
GL_RG16I |
i2 |
3 |
GL_RGB_INTEGER |
GL_RGB16I |
i2 |
4 |
GL_RGBA_INTEGER |
GL_RGBA16I |
i4
textures store 32 bit integers (GL_INT
)
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
i4 |
1 |
GL_RED_INTEGER |
GL_R32I |
i4 |
2 |
GL_RG_INTEGER |
GL_RG32I |
i4 |
3 |
GL_RGB_INTEGER |
GL_RGB32I |
i4 |
4 |
GL_RGBA_INTEGER |
GL_RGBA32I |
Normalized Integer Textures#
Normalized integers are integer texture, but texel reads in a shader
returns normalized values ([0.0, 1.0]
). For example an unsigned 16
bit fragment with the value 2**16-1
will be read as 1.0
.
Normalized integer textures should use the sampler2D sampler type. Also note that there’s no standard for normalized 32 bit integer textures because a float32 doesn’t have enough precision to express a 32 bit integer as a number between 0.0 and 1.0.
Unsigned#
nu1
textures is really the same as an f1
. Each component
is a GL_UNSIGNED_BYTE
, but are read by the shader in normalized
form [0.0, 1.0]
.
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
nu1 |
1 |
GL_RED |
GL_R8 |
nu1 |
2 |
GL_RG |
GL_RG8 |
nu1 |
3 |
GL_RGB |
GL_RGB8 |
nu1 |
4 |
GL_RGBA |
GL_RGBA8 |
nu2
textures store 16 bit unsigned integers (GL_UNSIGNED_SHORT
).
The value range [0, 2**16-1]
will be normalized into [0.0, 1.0]
.
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
nu2 |
1 |
GL_RED |
GL_R16 |
nu2 |
2 |
GL_RG |
GL_RG16 |
nu2 |
3 |
GL_RGB |
GL_RGB16 |
nu2 |
4 |
GL_RGBA |
GL_RGBA16 |
Signed#
ni1
textures store 8 bit signed integers (GL_BYTE
).
The value range [0, 127]
will be normalized into [0.0, 1.0]
.
Negative values will be clamped.
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
ni1 |
1 |
GL_RED |
GL_R8 |
ni1 |
2 |
GL_RG |
GL_RG8 |
ni1 |
3 |
GL_RGB |
GL_RGB8 |
ni1 |
4 |
GL_RGBA |
GL_RGBA8 |
ni2
textures store 16 bit signed integers (GL_SHORT
).
The value range [0, 2**15-1]
will be normalized into [0.0, 1.0]
.
Negative values will be clamped.
dtype |
Components |
Base Format |
Internal Format |
---|---|---|---|
ni2 |
1 |
GL_RED |
GL_R16 |
ni2 |
2 |
GL_RG |
GL_RG16 |
ni2 |
3 |
GL_RGB |
GL_RGB16 |
ni2 |
4 |
GL_RGBA |
GL_RGBA16 |
Overriding internalformat#
Context.texture()
supports overriding the internalformat
of the texture. This is only necessary when needing a different
internal formats from the tables above. This can for
example be GL_SRGB8 = 0x8C41
or some compressed format.
You may also need to look up in Context.extensions
to ensure the context supports internalformat you are using.
We do not provide the enum values for these alternative internalformats.
They can be looked up in the registry : https://raw.githubusercontent.com/KhronosGroup/OpenGL-Registry/master/xml/gl.xml
Example:
texture = ctx.texture(image.size, 3, data=srbg_data, internal_format=GL_SRGB8)