ImageData Class

Inheritance diagram of ImageData

class ImageData(width, height, format, data, pitch=None)

An image represented as a string of unsigned bytes.

Variables:
  • data – Pixel data, encoded according to format and pitch.
  • format – The format string to use when reading or writing data.
  • pitch – Number of bytes per row. Negative values indicate a top-to-bottom arrangement.

Setting the format and pitch instance variables and reading data is deprecated; use get_data and set_data in new applications. (Reading format and pitch to obtain the current encoding is not deprecated).

Constructor:

__init__(width, height, format, data, pitch=None)

Initialise image data.

Parameters:
  • width (int) – Width of image data
  • height (int) – Height of image data
  • format (str) – A valid format string, such as ‘RGB’, ‘RGBA’, ‘ARGB’, etc.
  • data (sequence) – String or array/list of bytes giving the decoded data.
  • pitch (int or None) – If specified, the number of bytes per row. Negative values indicate a top-to-bottom arrangement. Defaults to width * len(format).

Methods:

blit(x, y[, z, width, height])
blit_into(source, x, y, z) Draw source on this image.
blit_to_texture(target, level, x, y, z[, ...]) Draw this image to to the currently bound texture at target.
create_texture(cls[, rectangle, force_rectangle]) Create a texture containing this image.
get_data(format, pitch) Get the byte data of the image.
get_image_data()
get_mipmapped_texture() Return a Texture with mipmaps.
get_region(x, y, width, height) Retrieve a rectangular region of this image data.
get_texture([rectangle, force_rectangle])
save([filename, file, encoder]) Save this image to a file.
set_data(format, pitch, data) Set the byte data of the image.
set_mipmap_image(level, image) Set a mipmap image for a particular level.

Attributes:

anchor_x Type: int
anchor_y Type: int
data The byte data of the image.
format Format string of the data.
image_data An ImageData view of this image.
mipmapped_texture A Texture view of this image.
texture Get a Texture view of this image.

Methods

ImageData.blit(x, y, z=0, width=None, height=None)
ImageData.blit_to_texture(target, level, x, y, z, internalformat=None)

Draw this image to to the currently bound texture at target.

This image’s anchor point will be aligned to the given x and y coordinates. If the currently bound texture is a 3D texture, the z parameter gives the image slice to blit into.

If internalformat is specified, glTexImage is used to initialise the texture; otherwise, glTexSubImage is used to update a region.

ImageData.create_texture(cls, rectangle=False, force_rectangle=False)

Create a texture containing this image.

If the image’s dimensions are not powers of 2, a TextureRegion of a larger Texture will be returned that matches the dimensions of this image.

Parameters:
  • cls (class (subclass of Texture)) – Class to construct.
  • rectangle (bool) – True if a rectangle can be created; see AbstractImage.get_texture. Since: pyglet 1.1
  • force_rectangle (bool) – True if a rectangle must be created; see AbstractImage.get_texture. Since: pyglet 1.1.4
Return type:

cls or cls.region_class

ImageData.get_data(format, pitch)

Get the byte data of the image.

Parameters:
  • format (str) – Format string of the return data.
  • pitch (int) – Number of bytes per row. Negative values indicate a top-to-bottom arrangement.

Note

Since pyglet 1.1

Return type:sequence of bytes, or str
ImageData.get_image_data()
ImageData.get_mipmapped_texture()

Return a Texture with mipmaps.

If set_mipmap_image has been called with at least one image, the set of images defined will be used. Otherwise, mipmaps will be automatically generated.

The texture dimensions must be powers of 2 to use mipmaps.

Return type:Texture

Note

Since pyglet 1.1

ImageData.get_region(x, y, width, height)

Retrieve a rectangular region of this image data.

Parameters:
  • x (int) – Left edge of region.
  • y (int) – Bottom edge of region.
  • width (int) – Width of region.
  • height (int) – Height of region.
Return type:

ImageDataRegion

ImageData.get_texture(rectangle=False, force_rectangle=False)
ImageData.set_data(format, pitch, data)

Set the byte data of the image.

Parameters:
  • format (str) – Format string of the return data.
  • pitch (int) – Number of bytes per row. Negative values indicate a top-to-bottom arrangement.
  • data (str or sequence of bytes) – Image data.

Note

Since pyglet 1.1

ImageData.set_mipmap_image(level, image)

Set a mipmap image for a particular level.

The mipmap image will be applied to textures obtained via get_mipmapped_texture.

Parameters:
  • level (int) – Mipmap level to set image at, must be >= 1.
  • image (AbstractImage) – Image to set. Must have correct dimensions for that mipmap level (i.e., width >> level, height >> level)

Attributes

ImageData.data

The byte data of the image. Read-write.

Warning

Deprecated. Use get_data and set_data.

Type:sequence of bytes, or str
ImageData.format

Format string of the data. Read-write.

Type:str

Inherited members

Methods

ImageData.blit_into(source, x, y, z)

Draw source on this image.

source will be copied into this image such that its anchor point is aligned with the x and y parameters. If this image is a 3D texture, the z coordinate gives the image slice to copy into.

Note that if source is larger than this image (or the positioning would cause the copy to go out of bounds) then you must pass a region of source to this method, typically using get_region().

ImageData.save(filename=None, file=None, encoder=None)

Save this image to a file.

Parameters:
  • filename (str) – Used to set the image file format, and to open the output file if file is unspecified.
  • file (file-like object or None) – File to write image data to.
  • encoder (ImageEncoder or None) – If unspecified, all encoders matching the filename extension are tried. If all fail, the exception from the first one attempted is raised.

Attributes

ImageData.anchor_x = 0
ImageData.anchor_y = 0
ImageData.image_data

An ImageData view of this image.

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

Warning

Deprecated. Use get_image_data.

Type:ImageData
ImageData.mipmapped_texture

A Texture view of this image.

The returned Texture will have mipmaps filled in for all levels. Requires that image dimensions be powers of 2. Read-only.

Warning

Deprecated. Use get_mipmapped_texture.

Type:Texture
ImageData.texture

Get a Texture view of this image.

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

Warning

Deprecated. Use get_texture.

Type:Texture

Table Of Contents

Previous topic

DepthTexture Class

Next topic

ImageDataRegion Class