pyglet.graphics.texture

exception TextureArrayDepthExceeded: Exception occurs when depth has hit the maximum supported of the array.

exception TextureArraySizeExceeded: Exception occurs ImageData dimensions are larger than the array supports.

class CompressedTexture

__init__( width: int, height: int, tex_id: int, compression_format: CompressionFormat, tex_type: TextureType = TextureType.TYPE_2D, filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None, address_mode: AddressMode = AddressMode.REPEAT, anisotropic_level: int = 0, ) → None: Initialized in subclass.

get_image_data() → ImageData

Get an ImageData view of this image.

Changes to the returned instance may or may not be reflected in this image.

Return type:: ImageData

get_region( x: int, y: int, width: int, height: int, ) → _AbstractImage

Retrieve a rectangular region of this image.

Return type:: _AbstractImage

get_texture() → CompressedTexture

Return type:: CompressedTexture

default_filters: TextureFilter | tuple[TextureFilter, TextureFilter] = (TextureFilter.LINEAR, TextureFilter.LINEAR)

images = 1

level: int = 0: The mipmap level of this texture.

target: int: The GL texture target (e.g., GL_TEXTURE_2D).

tex_coords = (0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0): 12-tuple of float, named (u1, v1, r1, u2, v2, r2, …). u, v, r give the 3D texture coordinates for vertices 1-4. The vertices are specified in the order bottom-left, bottom-right, top-right and top-left.

tex_coords_order: tuple[int, int, int, int] = (0, 1, 2, 3): The default vertex winding order for a quad. This defaults to counter-clockwise, starting at the bottom-left.

x: int = 0

y: int = 0

z: int = 0

class Texture

An image loaded into GPU memory.

Typically, you will get an instance of Texture by accessing calling the get_texture() method of any AbstractImage class (such as ImageData).

region_class

The class to use when constructing regions of this texture. The class should be a subclass of TextureRegion.

alias of TextureRegion

classmethod create( width: int, height: int, tex_type: TextureType = TextureType.TYPE_2D, internal_format: ComponentFormat = ComponentFormat.RGBA, data_type: str = 'b', filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None, address_mode: AddressMode = AddressMode.REPEAT, anisotropic_level: int = 0, blank_data: bool = True, context: SurfaceContext | None = None, ) → Texture

Create a Texture.

Create a Texture with the specified dimensions, target and format. On return, the texture will be bound.

Parameters:

width (int) – Width of texture in pixels.
height (int) – Height of texture in pixels.
tex_type (TextureType) – The type of texture.
internal_format (ComponentFormat) – The components of the internal format.
data_type (str) – The data type of the internal format, as a struct string value.
filters (TextureFilter | tuple[TextureFilter, TextureFilter] | None) – The texture filter for the min and mag filters. If a single value is passed, both values will be used as the filter.
address_mode (AddressMode) – The wrapping address mode of the texture.
anisotropic_level (int) – The anisotropic level of the texture.
blank_data (bool) – If True, initialize the texture data with all zeros. If False, do not pass initial data.
context (SurfaceContext | None) – If multiple contexts are being used, a specified context the texture is tied to.

Return type:

Texture

classmethod create_from_image( image_data: ImageData | ImageDataRegion, tex_type: TextureType = TextureType.TYPE_2D, internal_format_size: int = 8, filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None, address_mode: AddressMode = AddressMode.REPEAT, anisotropic_level: int = 0, context: SurfaceContext | None = None, ) → Texture

Create a Texture from image data.

On return, the texture will be bound.

Parameters:

image_data (ImageData | ImageDataRegion) – The image instance.
tex_type (TextureType) – The type of texture.
internal_format_size (int) – The bit size of the internal format.
filters (TextureFilter | tuple[TextureFilter, TextureFilter] | None) – The texture filter for the min and mag filters. If a single value is passed, both values will be used as the filter.
address_mode (AddressMode) – The wrapping address mode of the texture.
anisotropic_level (int) – The anisotropic level of the texture.
context (SurfaceContext | None) – If multiple contexts are being used, a specified context the texture will be tied to.

Return type:

Texture

__init__( width: int, height: int, tex_id: int, tex_type: TextureType = TextureType.TYPE_2D, internal_format: ComponentFormat = ComponentFormat.RGBA, internal_format_size: int = 8, internal_format_type: str = 'b', filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None, address_mode: AddressMode = AddressMode.REPEAT, anisotropic_level: int = 0, ) → None: Initialized in subclass.

bind(texture_unit: int = 0) → None

Bind to a specific Texture Unit by number.

Return type:: None

blit( x: int, y: int, z: int = 0, width: int | None = None, height: int | None = None, ) → None

Blit the texture to the screen.

Removed as of 3.0. Instead, consider creating a Sprite with the Texture, and drawing it as part of a larger Batch.

Return type:: None

delete() → None

Delete this texture and the memory it occupies.

Textures are invalid after deletion, and may no longer be used.

Return type:: None

fetch(z: int = 0, level: int = 0) → ImageData

Fetch the image data of this texture by reading pixel data back from the GPU.

This can be a somewhat costly operation.

Modifying the returned ImageData object has no effect on the texture itself. Uploading ImageData back to the GPU/texture can be done with the upload() method.

Parameters:

z (int) – For 3D textures, the image slice to retrieve.
level (int) – The mipmap level of the texture to retrieve.

Return type:

ImageData

generate_mipmaps() → None

Generate mipmaps for this texture from the base level.

Return type:: None

get_image_data(z: int = 0) → ImageData

Get the image data of this texture.

Return type:: ImageData

get_mipmapped_texture() → Texture

Return type:: Texture

get_region( x: int, y: int, width: int, height: int, ) → TextureRegion

Retrieve a rectangular region of this image.

Return type:: TextureRegion

get_texture() → Texture

Return type:: Texture

get_transform( flip_x: bool = False, flip_y: bool = False, rotate: Literal[0, 90, 180, 270, 360] = 0, ) → TextureRegion

Create a copy of this image applying a simple transformation.

The transformation is applied to the texture coordinates only; get_image_data() will fetch the untransformed data from the GPU. The transformation is applied around the anchor point.

Parameters:

flip_x (bool) – If True, the returned image will be flipped horizontally.
flip_y (bool) – If True, the returned image will be flipped vertically.
rotate (Literal[0, 90, 180, 270, 360]) – Degrees of clockwise rotation of the returned image. Only 90-degree increments are supported.

Return type:

TextureRegion

init_mipmaps(levels: int | None = None, blank_data: bool = True) → int

Initialize mipmap levels for this texture.

Parameters:

levels (int | None) – The total number of mipmap levels to initialize. If None, the maximum number of mipmap levels for this texture size is used.
blank_data (bool) – If True, initialize levels with zeroed data. If False, allocate the levels without initializing their contents.

Return type:

int

upload( image: ImageData | ImageDataRegion, x: int, y: int, z: int, level: int = 0, ) → None

Upload image data into the Texture at specific coordinates.

You must have this texture bound before uploading data.

The image’s anchor point will be aligned to the given x and y coordinates. If this texture is a 3D texture, the z parameter gives the image slice to blit into. The level parameter specifies the mipmap level to upload to.

Return type:: None

default_filters: TextureFilter | tuple[TextureFilter, TextureFilter] = (TextureFilter.LINEAR, TextureFilter.LINEAR): The default minification and magnification filters, as a tuple. Both default to LINEAR. If a texture is created without specifying a filter, these defaults will be used.

property filters: tuple[TextureFilter, TextureFilter]

The current Texture filters.

Providing a single TextureFilter will adjust both minification and magnification filters. Otherwise, a tuple can be provided to adjust each individually.

images = 1

property mipmap_count: int: Return the number of mipmap levels initialized for this texture.

pixel_conversion = True

target: int: The GL texture target (e.g., GL_TEXTURE_2D).

tex_coords = (0, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0): 12-tuple of float, named (u1, v1, r1, u2, v2, r2, …). u, v, r give the 3D texture coordinates for vertices 1-4. The vertices are specified in the order bottom-left, bottom-right, top-right and top-left.

tex_coords_order: tuple[int, int, int, int] = (0, 1, 2, 3): The default vertex winding order for a quad. This defaults to counter-clockwise, starting at the bottom-left.

property uv: tuple[float, float, float, float]: Tuple containing the left, bottom, right, top 2D texture coordinates.

property valid_mipmaps: tuple[int, ...]: Return a sorted tuple of mipmap levels that currently have valid data.

x: int = 0

y: int = 0

z: int = 0

class Texture3D

A texture with more than one image slice.

Use the create_for_images() or create_for_image_grid() classmethod to construct a Texture3D.

classmethod create_for_images( images: Sequence[ImageData], internal_format_size: int = 8, internal_format_type: str = 'b', filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None, address_mode: AddressMode = AddressMode.REPEAT, anisotropic_level: int = 0, blank_data: bool = True, ) → Texture3D

Return type:: Texture3D

item_height: int = 0

item_width: int = 0

items: tuple

class TextureArray

region_class: alias of TextureArrayRegion

classmethod create( width: int, height: int, max_depth: int = 256, internal_format: ComponentFormat = ComponentFormat.RGBA, internal_format_size: int = 8, internal_format_type: str = 'b', filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None, address_mode: AddressMode = AddressMode.REPEAT, anisotropic_level: int = 0, context: SurfaceContext | None = None, ) → TextureArray

Create an empty TextureArray.

You may specify the maximum depth, or layers, the Texture Array should have. This defaults to 256, but will be hardware and driver dependent.

Parameters:

width (int) – Width of the texture.
height (int) – Height of the texture.
descriptor – Texture description.
max_depth (int) – The number of layers in the texture array.

Return type:

TextureArray

Added in version 2.0.

__init__( width: int, height: int, tex_id: int, max_depth: int, internal_format: ComponentFormat = ComponentFormat.RGBA, internal_format_size: int = 8, internal_format_type: str = 'b', filters: TextureFilter | tuple[TextureFilter, TextureFilter] | None = None, address_mode: AddressMode = AddressMode.REPEAT, anisotropic_level: int = 0, )

class TextureArrayRegion

A region of a TextureArray, presented as if it were a separate texture.

region_class: alias of TextureArrayRegion

class TextureGrid

A texture containing a regular grid of texture regions.

To construct, create an ImageGrid first:

image_grid = ImageGrid(...)
texture_grid = TextureGrid(image_grid)

The texture grid can be accessed as a single texture, or as a sequence of TextureRegion. When accessing as a sequence, you can specify integer indexes, in which the images are arranged in rows from the bottom-left to the top-right:

# assume the texture_grid is 3x3:
current_texture = texture_grid[3] # get the middle-left image

You can also specify tuples in the sequence methods, which are addressed as row, column:

# equivalent to the previous example:
current_texture = texture_grid[1, 0]

When using tuples in a slice, the returned sequence is over the rectangular region defined by the slice:

# returns center, center-right, center-top, top-right images in that
# order:
images = texture_grid[(1,1):]
# equivalent to
images = texture_grid[(1,1):(3,3)]

classmethod from_image_grid( image_grid: ImageGrid, ) → TextureGrid

Return type:: TextureGrid

__init__( texture: Texture | TextureRegion, rows: int, columns: int, item_width: int | None = None, item_height: int | None = None, row_padding: int = 0, column_padding: int = 0, ) → None

Construct a grid for the given image.

You can specify parameters for the grid, for example setting the padding between cells. Grids are always aligned to the bottom-left corner of the image.

Parameters:

texture (Texture | TextureRegion) – A texture or region over which to construct the grid.
rows (int) – Number of rows in the grid.
columns (int) – Number of columns in the grid.
item_width (int | None) – Width of each column. If unspecified, is calculated such that the entire texture width is used.
item_height (int | None) – Height of each row. If unspecified, is calculated such that the entire texture height is used.
row_padding (int) – Pixels separating adjacent rows. The padding is only inserted between rows, not at the edges of the grid.
column_padding (int) – Pixels separating adjacent columns. The padding is only inserted between columns, not at the edges of the grid.

class TextureRegion

A rectangular region of a texture, presented as if it were a separate texture.

__init__( x: int, y: int, z: int, width: int, height: int, owner: Texture, ): Initialized in subclass.

generate_mipmaps() → None

Generate mipmaps for this texture from the base level.

Return type:: None

init_mipmaps(levels: int | None = None, blank_data: bool = True) → int

Initialize mipmap levels for this texture.

Parameters:

levels (int | None) – The total number of mipmap levels to initialize. If None, the maximum number of mipmap levels for this texture size is used.
blank_data (bool) – If True, initialize levels with zeroed data. If False, allocate the levels without initializing their contents.

Return type:

int

property mipmap_count: int: Return the number of mipmap levels initialized for this texture.

property valid_mipmaps: tuple[int, ...]: Return a sorted tuple of mipmap levels that currently have valid data.

class TextureSequence

Interface for a sequence of textures.

Typical implementations store multiple Texture to minimise state changes.

get_texture_sequence() → TextureSequence[TTexture]

Get a TextureSequence.

Added in version 1.1.

Return type:: TextureSequence[TypeVar(TTexture, bound= Texture)]

class UniformTextureSequence: Interface for a sequence of textures, each with the same dimensions.