Class pyglet.image.ImageData

AbstractImage --+
                |
               ImageData

Known Subclasses:: ImageDataRegion

An image represented as a string of unsigned bytes.

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).

Methods

	__init__(self, width, height, format, data, pitch=None) Initialise image data.
	__getstate__(self)
ImageData	get_image_data(self) Get an ImageData view of this image.
sequence of bytes, or str	get_data(self, format, pitch) Get the byte data of the image.
	set_data(self, format, pitch, data) Set the byte data of the image.
	set_mipmap_image(self, level, image) Set a mipmap image for a particular level.
cls or cls.region_class	create_texture(self, cls, rectangle=False, force_rectangle=False) Create a texture containing this image.
Texture	get_texture(self, rectangle=False, force_rectangle=False) A Texture view of this image.
Texture	get_mipmapped_texture(self) Return a Texture with mipmaps.
ImageDataRegion	get_region(self, x, y, width, height) Retrieve a rectangular region of this image data.
	blit(self, x, y, z=0, width=None, height=None) Draw this image to the active framebuffers.
	blit_to_texture(self, target, level, x, y, z, internalformat=None) Draw this image to to the currently bound texture at `target`.
	__repr__(self) (Inherited from pyglet.image.AbstractImage)
	blit_into(self, source, x, y, z) Draw `source` on this image. (Inherited from pyglet.image.AbstractImage)
	save(self, filename=None, file=None, encoder=None) Save this image to a file. (Inherited from pyglet.image.AbstractImage)

Properties

ImageData	image_data An ImageData view of this image. (Inherited from pyglet.image.AbstractImage)
Texture	mipmapped_texture A Texture view of this image. (Inherited from pyglet.image.AbstractImage)
Texture	texture Get a Texture view of this image. (Inherited from pyglet.image.AbstractImage)

Instance Variables

str	format The format string to use when reading or writing data.
str	data Pixel data, encoded according to format and pitch.
int	anchor_x = `0` X coordinate of anchor, relative to left edge of image data (Inherited from pyglet.image.AbstractImage)
int	anchor_y = `0` Y coordinate of anchor, relative to bottom edge of image data (Inherited from pyglet.image.AbstractImage)
int	height Height of image (Inherited from pyglet.image.AbstractImage)
int	pitch Number of bytes per row.
int	width Width of image (Inherited from pyglet.image.AbstractImage)

Method Details

init

(Constructor) __init__(self, 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).

Overrides:

AbstractImage.__init__

get_image_data

get_image_data(self)

Get an ImageData view of this image.

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

Returns: ImageData
Overrides:: AbstractImage.get_image_data

Since: pyglet 1.1

get_data

get_data(self, 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.

Returns: sequence of bytes, or str

Since: pyglet 1.1

set_data

set_data(self, 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.

Since: pyglet 1.1

set_mipmap_image

set_mipmap_image(self, 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)

create_texture

create_texture(self, 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

Returns: cls or cls.region_class

get_texture

get_texture(self, rectangle=False, force_rectangle=False)

A Texture view of this image.

By default, textures are created with dimensions that are powers of two. Smaller images will return a TextureRegion that covers just the image portion of the larger texture. This restriction is required on older video cards, and for compressed textures, or where texture repeat modes will be used, or where mipmapping is desired.

If the rectangle parameter is True, this restriction is ignored and a texture the size of the image may be created if the driver supports the GL_ARB_texture_rectangle or GL_NV_texture_rectangle extensions. If the extensions are not present, the image already is a texture, or the image has power 2 dimensions, the rectangle parameter is ignored.

Examine Texture.target to determine if the returned texture is a rectangle (GL_TEXTURE_RECTANGLE_ARB or GL_TEXTURE_RECTANGLE_NV) or not (GL_TEXTURE_2D).

If the force_rectangle parameter is True, one of these extensions must be present, and the returned texture always has target GL_TEXTURE_RECTANGLE_ARB or GL_TEXTURE_RECTANGLE_NV.

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

Returns: Texture
Overrides:: AbstractImage.get_texture

Since: pyglet 1.1

get_mipmapped_texture

get_mipmapped_texture(self)

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.

Returns: Texture
Overrides:: AbstractImage.get_mipmapped_texture

Since: pyglet 1.1

get_region

get_region(self, 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.

Returns: ImageDataRegion

Overrides:

AbstractImage.get_region

blit

blit(self, x, y, z=0, width=None, height=None)

Draw this image to the active framebuffers.

The image will be drawn with the lower-left corner at (x - anchor_x, y - anchor_y, z).

Overrides:: AbstractImage.blit

blit_to_texture

blit_to_texture(self, 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.

Overrides:: AbstractImage.blit_to_texture

Instance Variable Details

format

The format string to use when reading or writing data.

Type:: str

data

Pixel data, encoded according to format and pitch.

Deprecated: Use get_data and set_data.

Type:: str

pitch

Number of bytes per row. Negative values indicate a top-to-bottom arrangement.

Type:: int