Texture3D
- class moderngl.Texture3D
A Texture is an OpenGL object that contains one or more images that all have the same image format.
A texture can be used in two ways. It can be the source of a texture access from a Shader, or it can be used as a render target.
A Texture3D object cannot be instantiated directly, it requires a context. Use
Context.texture3d()
to create one.
Create
- Context.texture3d(size: Tuple[int, int, int], components: int, data: Optional[Any] = None, *, alignment: int = 1, dtype: str = 'f1') Texture3D
Create a
Texture3D
object.- Parameters:
size (tuple) – The width, height and depth of the texture.
components (int) – The number of components 1, 2, 3 or 4.
data (bytes) – Content of the texture.
- Keyword Arguments:
alignment (int) – The byte alignment 1, 2, 4 or 8.
dtype (str) – Data type.
- Returns:
Texture3D
object
Methods
- Texture3D.read(*, alignment: int = 1) bytes
Read the pixel data as bytes into system memory.
- Keyword Arguments:
alignment (int) – The byte alignment of the pixels.
- Returns:
bytes
- Texture3D.read_into(buffer: Any, *, alignment: int = 1, write_offset: int = 0) None
Read the content of the texture 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.texture3d((2, 2, 2), 1) texture.read_into(data) # Reading pixel data into a buffer data = ctx.buffer(reserve=8) texture = ctx.texture3d((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.
- Texture3D.write(data: Any, viewport: Optional[Union[Tuple[int, int, int], Tuple[int, int, int, int, int, int]]] = None, *, alignment: int = 1) None
Update the content of the texture from byte data or a moderngl
Buffer
.Examples:
# Write data from a moderngl Buffer data = ctx.buffer(reserve=8) texture = ctx.texture3d((2, 2, 2), 1) texture.write(data) # Write data from bytes data = b'\xff\xff\xff\xff\xff\xff\xff\xff' texture = ctx.texture3d((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.
- Texture3D.build_mipmaps(base: int = 0, max_level: int = 1000) None
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
- Texture3D.bind_to_image(unit: int, read: bool = True, write: bool = True, level: int = 0, format: int = 0) None
Bind a texture to an image unit (OpenGL 4.2 required).
This is used to bind textures to image units for shaders. The idea with image load/store is that the user can bind one of the images in a Texture to a number of image binding points (which are separate from texture image units). Shaders can read information from these images and write information to them, in ways that they cannot with textures.
It’s important to specify the right access type for the image. This can be set with the
read
andwrite
arguments. Allowed combinations are:Read-only:
read=True
andwrite=False
Write-only:
read=False
andwrite=True
Read-write:
read=True
andwrite=True
format
specifies the format that is to be used when performing formatted stores into the image from shaders.format
must be compatible with the texture’s internal format. By default the format of the texture is passed in. The format parameter is only needed when overriding this behavior.Note that we bind the 3D textured layered making the entire texture readable and writable. It is possible to bind a specific 2D section in the future.
More information:
- Parameters:
unit (int) – Specifies the index of the image unit to which to bind the texture
texture (
moderngl.Texture
) – The texture to bind
- Keyword Arguments:
read (bool) – Allows the shader to read the image (default:
True
)write (bool) – Allows the shader to write to the image (default:
True
)level (int) – Level of the texture to bind (default:
0
).format (int) – (optional) The OpenGL enum value representing the format (defaults to the texture’s format)
- Texture3D.use(location: int = 0) None
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
sampler3D
uniform in the shader because samplers read from the texture unit we assign to them:# Define what texture unit our two sampler3D 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.
- Texture3D.release() None
Release the ModernGL object.
Attributes
- Texture3D.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
- Texture3D.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
- Texture3D.repeat_z
The z repeat flag for the texture (Default
True
).Example:
# Enable texture repeat (GL_REPEAT) texture.repeat_z = True # Disable texture repeat (GL_CLAMP_TO_EDGE) texture.repeat_z = False
- Type:
bool
- Texture3D.filter
The filter of the texture.
- Type:
tuple
- Texture3D.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
- Texture3D.width
The width of the texture.
- Type:
int
- Texture3D.height
The height of the texture.
- Type:
int
- Texture3D.depth
The depth of the texture.
- Type:
int
- Texture3D.size
The size of the texture.
- Type:
tuple
- Texture3D.dtype
Data type.
- Type:
str
- Texture3D.components
The number of components of the texture.
- Type:
int
- Texture3D.glo
The internal OpenGL object.
This values is provided for debug purposes only.
- Type:
int
- Texture3D.mglo
Internal representation for debug purposes only.
- Texture3D.extra
Any - Attribute for storing user defined objects
- Texture3D.ctx
The context this object belongs to