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.

Keyword Arguments:
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.
	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 a Buffer 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)

Keyword Arguments:
Parameters:	buffer (Union[bytearray, Buffer]) – The buffer that will receive the pixels.
	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)

Keyword Arguments:
Parameters:	data (bytes) – The pixel data. viewport (tuple) – The viewport.
	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 in 6.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 the texture() 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 range 1.0 and ctx.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