Texture#

class arcade.gl.Texture(ctx: Context, size: Tuple[int, int], *, components: int = 4, dtype: str = 'f1', data: Optional[Union[ByteString, memoryview, array]] = None, filter: Tuple[c_uint, c_uint] = None, wrap_x: c_uint = None, wrap_y: c_uint = None, target=3553, depth=False, samples: int = 0, immutable: bool = False)[source]#

Bases: object

An OpenGL 2D texture. We can create an empty black texture or a texture from byte data. A texture can also be created with different datatypes such as float, integer or unsigned integer.

The best way to create a texture instance is through arcade.gl.Context.texture()

Supported dtype values are:

# Float formats
'f1': UNSIGNED_BYTE
'f2': HALF_FLOAT
'f4': FLOAT
# int formats
'i1': BYTE
'i2': SHORT
'i4': INT
# uint formats
'u1': UNSIGNED_BYTE
'u2': UNSIGNED_SHORT
'u4': UNSIGNED_INT
Parameters:

  • ctx (Context) – The context the object belongs to

  • size (Tuple[int, int]) – The size of the texture

  • components (int) – The number of components (1: R, 2: RG, 3: RGB, 4: RGBA)

  • dtype (str) – The data type of each component: f1, f2, f4 / i1, i2, i4 / u1, u2, u4

  • data (BufferProtocol) – The texture data (optional). Can be bytes or any object supporting the buffer protocol.

  • filter (Tuple[gl.GLuint,gl.GLuint]) – The minification/magnification filter of the texture

  • wrap_x (gl.GLuint) – Wrap mode x

  • wrap_y (gl.GLuint) – Wrap mode y

  • target (int) – The texture type (Ignored. Legacy)

  • depth (bool) – creates a depth texture if True

  • samples (int) – Creates a multisampled texture for values > 0. This value will be clamped between 0 and the max sample capability reported by the drivers.

  • immutable (bool) – Make the storage (not the contents) immutable. This can sometimes be required when using textures with compute shaders.

resize(size: Tuple[int, int])[source]#

Resize the texture. This will re-allocate the internal memory and all pixel data will be lost.

property ctx: Context#

The context this texture belongs to

Type:

Context

property glo: c_uint#

The OpenGL texture id

Type:

GLuint

property width: int#

The width of the texture in pixels

Type:

int

property height: int#

The height of the texture in pixels

Type:

int

property dtype: str#

The data type of each component

Type:

str

property size: Tuple[int, int]#

The size of the texture as a tuple

Type:

tuple (width, height)

property samples: int#

Number of samples if multisampling is enabled (read only)

Type:

int

property byte_size: int#

The byte size of the texture.

Type:

int

property components: int#

Number of components in the texture

Type:

int

property depth: bool#

If this is a depth texture.

Type:

bool

property immutable: bool#

Does this texture have immutable storage?

Type:

bool

property swizzle: str#

str: 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'
property filter: Tuple[int, int]#

Get or set the (min, mag) filter for this texture. These are rules for how a texture interpolates. The filter is specified for minification and magnification.

Default value is LINEAR, LINEAR. Can be set to NEAREST, NEAREST for pixelated graphics.

When mipmapping is used the min filter needs to be one of the MIPMAP variants.

Accepted values:

# Enums can be accessed on the context or arcade.gl
NEAREST                # Nearest pixel
LINEAR                 # Linear interpolate
NEAREST_MIPMAP_NEAREST # Minification filter for mipmaps
LINEAR_MIPMAP_NEAREST  # Minification filter for mipmaps
NEAREST_MIPMAP_LINEAR  # Minification filter for mipmaps
LINEAR_MIPMAP_LINEAR   # Minification filter for mipmaps

Also see

Type:

tuple (min filter, mag filter)

property wrap_x: int#

Get or set the horizontal wrapping of the texture. This decides how textures are read when texture coordinates are outside the [0.0, 1.0] area. Default value is REPEAT.

Valid options are:

# Note: Enums can also be accessed in arcade.gl
# Repeat pixels on the y axis
texture.wrap_x = ctx.REPEAT
# Repeat pixels on the y axis mirrored
texture.wrap_x = ctx.MIRRORED_REPEAT
# Repeat the edge pixels when reading outside the texture
texture.wrap_x = ctx.CLAMP_TO_EDGE
# Use the border color (black by default) when reading outside the texture
texture.wrap_x = ctx.CLAMP_TO_BORDER
Type:

int

property wrap_y: int#

Get or set the horizontal wrapping of the texture. This decides how textures are read when texture coordinates are outside the [0.0, 1.0] area. Default value is REPEAT.

Valid options are:

# Note: Enums can also be accessed in arcade.gl
# Repeat pixels on the x axis
texture.wrap_x = ctx.REPEAT
# Repeat pixels on the x axis mirrored
texture.wrap_x = ctx.MIRRORED_REPEAT
# Repeat the edge pixels when reading outside the texture
texture.wrap_x = ctx.CLAMP_TO_EDGE
# Use the border color (black by default) when reading outside the texture
texture.wrap_x = ctx.CLAMP_TO_BORDER
Type:

int

property anisotropy: float#

Get or set the anisotropy for this texture.

property compare_func: Optional[str]#

Get or set the compare function for a depth texture:

texture.compare_func = None  # Disable depth comparison completely
texture.compare_func = '<='  # GL_LEQUAL
texture.compare_func = '<'   # GL_LESS
texture.compare_func = '>='  # GL_GEQUAL
texture.compare_func = '>'   # GL_GREATER
texture.compare_func = '=='  # GL_EQUAL
texture.compare_func = '!='  # GL_NOTEQUAL
texture.compare_func = '0'   # GL_NEVER
texture.compare_func = '1'   # GL_ALWAYS
Type:

str

read(level: int = 0, alignment: int = 1) → bytearray[source]#

Read the contents of the texture.

Parameters:

  • level (int) – The texture level to read

  • alignment (int) – Alignment of the start of each row in memory in number of bytes. Possible values: 1,2,4

Return type:

bytearray

write(data: Union[ByteString, memoryview, array, Buffer], level: int = 0, viewport=None) → None[source]#

Write byte data from the passed source to the texture.

The data value can be either an arcade.gl.Buffer or anything that implements the Buffer Protocol.

The latter category includes bytes, bytearray, array.array, and more. You may need to use typing workarounds for non-builtin types. See Writing Raw Bytes to GL Buffers & Textures for more information.

Parameters:

  • data (BufferOrBufferProtocol) – Buffer or buffer protocol object with data to write.

  • level (int) – The texture level to write

  • viewport (Union[Tuple[int, int], Tuple[int, int, int, int]]) – The area of the texture to write. 2 or 4 component tuple

build_mipmaps(base: int = 0, max_level: int = 1000) → None[source]#

Generate mipmaps for this texture.

The default values usually work well.

Mipmaps are successively smaller versions of an original texture with special filtering applied. Using mipmaps allows OpenGL to render scaled versions of original textures with fewer scaling artifacts.

Mipmaps can be made for textures of any size. Each mipmap version halves the width and height of the previous one (e.g. 256 x 256, 128 x 128, 64 x 64, etc) down to a minimum of 1 x 1.

Note

Mipmaps will only be used if a texture’s filter is configured with a mipmap-type minification:

# Set up linear interpolating minification filter
texture.filter = ctx.LINEAR_MIPMAP_LINEAR, ctx.LINEAR
Parameters:

  • base (int) – Level the mipmaps start at (usually 0)

  • max_level (int) – The maximum number of levels to generate

Also see: https://www.khronos.org/opengl/wiki/Texture#Mip_maps

delete()[source]#

Destroy the underlying OpenGL resource. Don’t use this unless you know exactly what you are doing.

static delete_glo(ctx: Context, glo: c_uint)[source]#

Destroy the texture. This is called automatically when the object is garbage collected.

Parameters:

  • ctx (arcade.gl.Context) – OpenGL Context

  • glo (gl.GLuint) – The OpenGL texture id

use(unit: int = 0) → None[source]#

Bind the texture to a channel,

Parameters:

unit (int) – The texture unit to bind the texture.

bind_to_image(unit: int, read: bool = True, write: bool = True, level: int = 0)[source]#

Bind textures to image units.

Note that either or both read and write needs to be True. The supported modes are: read only, write only, read-write

Parameters:

  • unit (int) – The image unit

  • read (bool) – The compute shader intends to read from this image

  • write (bool) – The compute shader intends to write to this image

  • level (int) –