Texture
- class arcade.gl.Texture2D(ctx: Context, size: tuple[int, int], *, components: int = 4, dtype: str = 'f1', data: BufferProtocol | None = None, filter: tuple[PyGLuint, PyGLuint] | None = None, wrap_x: PyGLuint | None = None, wrap_y: PyGLuint | None = None, target=3553, depth=False, samples: int = 0, immutable: bool = False, internal_format: PyGLuint | None = None, compressed: bool = False, compressed_data: bool = False)[source]
Bases:
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 – The context the object belongs to
size – The size of the texture
components – The number of components (1: R, 2: RG, 3: RGB, 4: RGBA)
dtype – The data type of each component: f1, f2, f4 / i1, i2, i4 / u1, u2, u4
data – The texture data (optional). Can be bytes or any object supporting the buffer protocol.
filter – The minification/magnification filter of the texture
wrap_x – Wrap mode x
wrap_y – Wrap mode y
target – The texture type (Ignored. Legacy)
depth – creates a depth texture if True
samples – Creates a multisampled texture for values > 0. This value will be clamped between 0 and the max sample capability reported by the drivers.
immutable – Make the storage (not the contents) immutable. This can sometimes be required when using textures with compute shaders.
internal_format – The internal format of the texture
compressed – Is the texture compressed?
compressed_data – The raw compressed data
- resize(size: tuple[int, int])[source]
Resize the texture. This will re-allocate the internal memory and all pixel data will be lost.
Note
Immutable textures cannot be resized.
- Parameters:
size – The new size of the texture
- property swizzle: str
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'
- 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 toNEAREST, 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
- 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 isREPEAT
.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
- 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 isREPEAT
.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
- property compare_func: str | None
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
- read(level: int = 0, alignment: int = 1) bytes [source]
Read the contents of the texture.
- Parameters:
level – The texture level to read
alignment – Alignment of the start of each row in memory in number of bytes. Possible values: 1,2,4
- write(data: ByteString | memoryview | array | 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 anarcade.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 –
Buffer
or buffer protocol object with data to write.level – The texture level to write
viewport – 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 – Level the mipmaps start at (usually 0)
max_level – 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: gl.GLuint)[source]
Destroy the texture.
This is called automatically when the object is garbage collected.
- Parameters:
ctx – OpenGL Context
glo – The OpenGL texture id
- use(unit: int = 0) None [source]
Bind the texture to a channel,
- Parameters:
unit – 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
andwrite
needs to beTrue
. The supported modes are: read only, write only, read-write- Parameters:
unit – The image unit
read – The compute shader intends to read from this image
write – The compute shader intends to write to this image
level – The mipmap level to bind
- get_handle(resident: bool = True) int [source]
Get a handle for bindless texture access.
Once a handle is created its parameters cannot be changed. Attempting to do so will have no effect. (filter, wrap etc). There is no way to undo this immutability.
Handles cannot be used by shaders until they are resident. This method can be called multiple times to move a texture in and out of residency:
>> texture.get_handle(resident=False) 4294969856 >> texture.get_handle(resident=True) 4294969856
Ths same handle is returned if the handle already exists.
Note
Limitations from the OpenGL wiki
The amount of storage available for resident images/textures may be less than the total storage for textures that is available. As such, you should attempt to minimize the time a texture spends being resident. Do not attempt to take steps like making textures resident/un-resident every frame or something. But if you are finished using a texture for some time, make it un-resident.
- Parameters:
resident – Make the texture resident.