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.
Float Textures¶
f1
textures are just unsigned bytes (8 bits per component) (GL_UNSIGNED_BYTE
)
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 usampler2D
(unsigned) or isampler2D
(signed).
Unsigned¶
u1
textures store unsigned byte values (GL_UNSIGNED_BYTE
).
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¶
u1
textures store signed byte values (GL_BYTE
).
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 |
u2
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 |
u4
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 |
Overriding internalformat¶
Context.texture()
supports overriding the internalformat
of the texture. This is only necessary when needing a different
internalformats 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)