TextureArray
- class moderngl.TextureArray
An Array Texture is a Texture where each mipmap level contains an array of images of the same size. Array textures may have Mipmaps, but each mipmap in the texture has the same number of levels.
A TextureArray object cannot be instantiated directly, it requires a context. Use
Context.texture_array()
to create one.
Create
- Context.texture_array(size, components, data=None, alignment=1, dtype='f1') TextureArray
Create a
TextureArray
object.- Parameters
size (tuple) – The
(width, height, layers)
of the texture.components (int) – The number of components 1, 2, 3 or 4.
data (bytes) – Content of the texture. The size must be
(width, height * layers)
so each layer is stacked vertically.
- Keyword Arguments
alignment (int) – The byte alignment 1, 2, 4 or 8.
dtype (str) – Data type.
- Returns
Texture3D
object
Methods
- TextureArray.read(alignment=1) bytes
Read the pixel data as bytes into system memory.
- Keyword Arguments
alignment (int) – The byte alignment of the pixels.
- Returns
bytes
- TextureArray.read_into(buffer, alignment=1, write_offset=0)
Read the content of the texture array into a bytearray or
Buffer
. The advantage of reading into aBuffer
is that pixel data does not need to travel all the way to system memory:# Reading pixel data into a bytearray data = bytearray(8) texture = ctx.texture((2, 2, 2), 1) texture.read_into(data) # Reading pixel data into a buffer data = ctx.buffer(reserve=8) texture = ctx.texture((2, 2, 2), 1) texture.read_into(data)
- Parameters
buffer (Union[bytearray, Buffer]) – The buffer that will receive the pixels.
- Keyword Arguments
alignment (int) – The byte alignment of the pixels.
write_offset (int) – The write offset.
- TextureArray.write(data, viewport=None, alignment=1)
Update the content of the texture array from byte data or a moderngl
Buffer
.The
viewport
can be used for finer control of where the data should be written in the array. The valid versions are:# Writing multiple layers from the begining of the texture texture.write(data, viewport=(width, hight, num_layers)) # Writing sub-sections of the array texture.write(data, viewport=(x, y, layer, width, height, num_layers))
Like with other texture types we can also use bytes or
Buffer
as a source:# Using a moderngl buffer data = ctx.buffer(reserve=8) texture = ctx.texture_array((2, 2, 2), 1) texture.write(data) # Using byte data from system memory data = b"ÿÿÿÿÿÿÿÿ" texture = ctx.texture_array((2, 2, 2), 1) texture.write(data)
- Parameters
data (bytes) – The pixel data.
viewport (tuple) – The viewport.
- Keyword Arguments
alignment (int) – The byte alignment of the pixels.
- TextureArray.build_mipmaps(base=0, max_level=1000)
Generate mipmaps.
This also changes the texture filter to
LINEAR_MIPMAP_LINEAR, LINEAR
(Will be removed in6.x
)- Keyword Arguments
base (int) – The base level
max_level (int) – The maximum levels to generate
- TextureArray.use(location=0)
Bind the texture to a texture unit.
The location is the texture unit we want to bind the texture. This should correspond with the value of the
sampler2DArray
uniform in the shader because samplers read from the texture unit we assign to them:# Define what texture unit our two sampler2DArray uniforms should represent program['texture_a'] = 0 program['texture_b'] = 1 # Bind textures to the texture units first_texture.use(location=0) second_texture.use(location=1)
- Parameters
location (int) – The texture location/unit.
- TextureArray.release()
Release the ModernGL object.
Attributes
- TextureArray.repeat_x
The x repeat flag for the texture (Default
True
)Example:
# Enable texture repeat (GL_REPEAT) texture.repeat_x = True # Disable texture repeat (GL_CLAMP_TO_EDGE) texture.repeat_x = False
- Type
bool
- TextureArray.repeat_y
The y repeat flag for the texture (Default
True
)Example:
# Enable texture repeat (GL_REPEAT) texture.repeat_y = True # Disable texture repeat (GL_CLAMP_TO_EDGE) texture.repeat_y = False
- Type
bool
- TextureArray.filter
The minification and magnification filter for the texture. (Default
(moderngl.LINEAR. moderngl.LINEAR)
)Example:
texture.filter == (moderngl.NEAREST, moderngl.NEAREST) texture.filter == (moderngl.LINEAR_MIPMAP_LINEAR, moderngl.LINEAR) texture.filter == (moderngl.NEAREST_MIPMAP_LINEAR, moderngl.NEAREST) texture.filter == (moderngl.LINEAR_MIPMAP_NEAREST, moderngl.NEAREST)
- Type
tuple
- TextureArray.swizzle
The swizzle mask of the texture (Default
'RGBA'
).The swizzle mask change/reorder the
vec4
value returned by thetexture()
function in a GLSL shaders. This is represented by a 4 character string were each character can be:'R' GL_RED 'G' GL_GREEN 'B' GL_BLUE 'A' GL_ALPHA '0' GL_ZERO '1' GL_ONE
Example:
# Alpha channel will always return 1.0 texture.swizzle = 'RGB1' # Only return the red component. The rest is masked to 0.0 texture.swizzle = 'R000' # Reverse the components texture.swizzle = 'ABGR'
- Type
str
- TextureArray.anisotropy
Number of samples for anisotropic filtering (Default
1.0
). The value will be clamped in range1.0
andctx.max_anisotropy
.Any value greater than 1.0 counts as a use of anisotropic filtering:
# Disable anisotropic filtering texture.anisotropy = 1.0 # Enable anisotropic filtering suggesting 16 samples as a maximum texture.anisotropy = 16.0
- Type
float
- TextureArray.width
The width of the texture array.
- Type
int
- TextureArray.height
The height of the texture array.
- Type
int
- TextureArray.layers
The number of layers of the texture array.
- Type
int
- TextureArray.size
The size of the texture array.
- Type
tuple
- TextureArray.dtype
Data type.
- Type
str
- TextureArray.components
The number of components of the texture array.
- Type
int
- TextureArray.glo
The internal OpenGL object. This values is provided for debug purposes only.
- Type
int
- TextureArray.mglo
Internal representation for debug purposes only.
- TextureArray.extra
Any - Attribute for storing user defined objects
- TextureArray.ctx
The context this object belongs to