Cogl.Texture

g Cogl.Texture Cogl.Texture GObject.GInterface GObject.GInterface GObject.GInterface->Cogl.Texture

Implementations:

Cogl.Texture2D, Cogl.Texture2DSliced, Cogl.Texture3D, Cogl.TextureRectangle

Methods

allocate ()

get_components ()

get_data (format, rowstride, data)

get_gl_texture ()

get_height ()

get_max_waste ()

get_premultiplied ()

get_width ()

is_sliced ()

set_components (components)

set_data (format, rowstride, data, level)

set_premultiplied (premultiplied)

set_region (src_x, src_y, dst_x, dst_y, dst_width, dst_height, width, height, format, rowstride, data)

set_region_from_bitmap (src_x, src_y, dst_x, dst_y, dst_width, dst_height, bitmap)

Virtual Methods

None

Properties

None

Signals

None

Fields

None

Class Details

class Cogl.Texture
Bases:

GObject.GInterface

allocate()
Raises:

GLib.Error

Returns:

True if the texture was successfully allocated, otherwise False and error will be updated if it wasn’t None.

Return type:

int

Explicitly allocates the storage for the given self which allows you to be sure that there is enough memory for the texture and if not then the error can be handled gracefully.

Normally applications don’t need to use this api directly since the texture will be implicitly allocated when data is set on the texture, or if the texture is attached to a #CoglOffscreen framebuffer and rendered too.

get_components()
Return type:

Cogl.TextureComponents

Queries what components the given self stores internally as set via Cogl.Texture.set_components().

For textures created by the ‘_with_size’ constructors the default is Cogl.TextureComponents.RGBA. The other constructors which take a Cogl.Bitmap or a data pointer default to the same components as the pixel format of the data.

New in version 1.18.

get_data(format, rowstride, data)
Parameters:

  • format (Cogl.PixelFormat) – the Cogl.PixelFormat to store the texture as.

  • rowstride (int) – the rowstride of data in bytes or pass 0 to calculate from the bytes-per-pixel of format multiplied by the self width.

  • data (int) – memory location to write the self's contents, or None to only query the data size through the return value.

Returns:

the size of the texture data in bytes

Return type:

int

Copies the pixel data from a cogl texture to system memory.

Don’t pass the value of cogl_texture_get_rowstride() as the rowstride argument, the rowstride should be the rowstride you want for the destination data buffer not the rowstride of the source texture

get_gl_texture()
Returns:

True if the handle was successfully retrieved, False if the handle was invalid

out_gl_handle:

pointer to return location for the textures GL handle, or None.

out_gl_target:

pointer to return location for the GL target type, or None.

Return type:

(int, out_gl_handle: int, out_gl_target: int)

Queries the GL handles for a GPU side texture through its Cogl.Texture.

If the texture is spliced the data for the first sub texture will be queried.

get_height()
Returns:

the height of the GPU side texture in pixels

Return type:

int

Queries the height of a cogl texture.

get_max_waste()
Returns:

the maximum waste

Return type:

int

Queries the maximum wasted (unused) pixels in one dimension of a GPU side texture.

get_premultiplied()
Returns:

True if red, green and blue components are internally stored pre-multiplied by the alpha value or False if not.

Return type:

int

Queries the pre-multiplied alpha status for internally stored red, green and blue components for the given self as set by Cogl.Texture.set_premultiplied().

By default the pre-multipled state is True.

New in version 1.18.

get_width()
Returns:

the width of the GPU side texture in pixels

Return type:

int

Queries the width of a cogl texture.

is_sliced()
Returns:

True if the texture is sliced, False if the texture is stored as a single GPU texture

Return type:

int

Queries if a texture is sliced (stored as multiple GPU side tecture objects).

set_components(components)
Parameters:

components (Cogl.TextureComponents) –

Affects the internal storage format for this texture by specifying what components will be required for sampling later.

This api affects how data is uploaded to the GPU since unused components can potentially be discarded from source data.

For textures created by the ‘_with_size’ constructors the default is Cogl.TextureComponents.RGBA. The other constructors which take a Cogl.Bitmap or a data pointer default to the same components as the pixel format of the data.

Note that the Cogl.TextureComponents.RG format is not available on all drivers. The availability can be determined by checking for the Cogl.FeatureID.OGL_FEATURE_ID_TEXTURE_RG feature. If this format is used on a driver where it is not available then Cogl.TextureError.FORMAT will be raised when the texture is allocated. Even if the feature is not available then Cogl.PixelFormat.RG_88 can still be used as an image format as long as Cogl.TextureComponents.RG isn’t used as the texture’s components.

New in version 1.18.

set_data(format, rowstride, data, level)
Parameters:

  • format (Cogl.PixelFormat) – the Cogl.PixelFormat used in the source data buffer.

  • rowstride (int) – rowstride of the source data buffer (computed from the texture width and format if it equals 0)

  • data (int) – the source data, pointing to the first top-left pixel to set

  • level (int) – The mipmap level to update (Normally 0 for the largest, base texture)

Raises:

GLib.Error

Returns:

True if the data upload was successful, and False otherwise

Return type:

int

self a Cogl.Texture. Sets all the pixels for a given mipmap level by copying the pixel data pointed to by the data argument into the given self.

data should point to the first pixel to copy corresponding to the top left of the mipmap level being set.

If rowstride equals 0 then it will be automatically calculated from the width of the mipmap level and the bytes-per-pixel for the given format.

A mipmap level of 0 corresponds to the largest, base image of a texture and level 1 is half the width and height of level 0. If dividing any dimension of the previous level by two results in a fraction then round the number down (floor()), but clamp to 1 something like this:

next_width = MAX (1, floor (prev_width));

You can determine the number of mipmap levels for a given texture like this:

n_levels = 1 + floor (log2 (max_dimension));

Where %max_dimension is the larger of Cogl.Texture.get_width() and Cogl.Texture.get_height().

It is an error to pass a level number >= the number of levels that self can have according to the above calculation.

Since the storage for a Cogl.Texture is allocated lazily then if the given self has not previously been allocated then this api can return False and throw an exceptional error if there is not enough memory to allocate storage for self.

set_premultiplied(premultiplied)
Parameters:

premultiplied (int) – Whether any internally stored red, green or blue components are pre-multiplied by an alpha component.

Affects the internal storage format for this texture by specifying whether red, green and blue color components should be stored as pre-multiplied alpha values.

This api affects how data is uploaded to the GPU since Cogl will convert source data to have premultiplied or unpremultiplied components according to this state.

For example if you create a texture via Cogl.Texture2D.new_with_size() and then upload data via Cogl.Texture.set_data() passing a source format of Cogl.PixelFormat.RGBA_8888 then Cogl will internally multiply the red, green and blue components of the source data by the alpha component, for each pixel so that the internally stored data has pre-multiplied alpha components. If you instead upload data that already has pre-multiplied components by passing Cogl.PixelFormat.RGBA_8888_PRE as the source format to Cogl.Texture.set_data() then the data can be uploaded without being converted.

By default the premultipled state is True.

New in version 1.18.

set_region(src_x, src_y, dst_x, dst_y, dst_width, dst_height, width, height, format, rowstride, data)
Parameters:

  • src_x (int) – upper left coordinate to use from source data.

  • src_y (int) – upper left coordinate to use from source data.

  • dst_x (int) – upper left destination horizontal coordinate.

  • dst_y (int) – upper left destination vertical coordinate.

  • dst_width (int) – width of destination region to write. (Must be less than or equal to width)

  • dst_height (int) – height of destination region to write. (Must be less than or equal to height)

  • width (int) – width of source data buffer.

  • height (int) – height of source data buffer.

  • format (Cogl.PixelFormat) – the Cogl.PixelFormat used in the source buffer.

  • rowstride (int) – rowstride of source buffer (computed from width if none specified)

  • data (int) – the actual pixel data.

Returns:

True if the subregion upload was successful, and False otherwise

Return type:

int

Sets the pixels in a rectangular subregion of self from an in-memory buffer containing pixel data.

The region set can’t be larger than the source data

set_region_from_bitmap(src_x, src_y, dst_x, dst_y, dst_width, dst_height, bitmap)
Parameters:

  • src_x (int) – upper left coordinate to use from the source bitmap.

  • src_y (int) – upper left coordinate to use from the source bitmap

  • dst_x (int) – upper left destination horizontal coordinate.

  • dst_y (int) – upper left destination vertical coordinate.

  • dst_width (int) – width of destination region to write. (Must be less than or equal to the bitmap width)

  • dst_height (int) – height of destination region to write. (Must be less than or equal to the bitmap height)

  • bitmap (Cogl.Bitmap) – The source bitmap to read from

Returns:

True if the subregion upload was successful, and False otherwise

Return type:

int

Copies a specified source region from bitmap to the position (src_x, src_y) of the given destination texture handle.

The region updated can’t be larger than the source bitmap

New in version 1.8.