Cogl.Texture

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

Implementations:
 None

Methods

class error_quark ()
class new_from_bitmap (bitmap, flags, internal_format)
class new_from_data (width, height, flags, format, internal_format, rowstride, data)
class new_from_file (filename, flags, internal_format)
class new_from_foreign (gl_handle, gl_target, width, height, x_pot_waste, y_pot_waste, format)
class new_with_size (width, height, flags, internal_format)
  allocate ()
  get_components ()
  get_data (format, rowstride, data)
  get_gl_texture ()
  get_height ()
  get_max_waste ()
  get_premultiplied ()
  get_width ()
  is_sliced ()
  new_from_sub_texture (sub_x, sub_y, sub_width, sub_height)
  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
classmethod error_quark()
Return type:int
classmethod new_from_bitmap(bitmap, flags, internal_format)
Parameters:
Returns:

A newly created Cogl.Texture or None on failure

Return type:

Cogl.Texture

Creates a Cogl.Texture from a Cogl.Bitmap.

New in version 1.0.

Deprecated since version 1.18: Use specific constructors such as cogl_texture_2d_new_from_bitmap()

classmethod new_from_data(width, height, flags, format, internal_format, rowstride, data)
Parameters:
  • width (int) – width of texture in pixels
  • height (int) – height of texture in pixels
  • flags (Cogl.TextureFlags) – Optional flags for the texture, or Cogl.TextureFlags.NONE
  • format (Cogl.PixelFormat) – the Cogl.PixelFormat the buffer is stored in in RAM
  • internal_format (Cogl.PixelFormat) – the Cogl.PixelFormat that will be used for storing the buffer on the GPU. If Cogl.PixelFormat.ANY is given then a premultiplied format similar to the format of the source data will be used. The default blending equations of Cogl expect premultiplied color data; the main use of passing a non-premultiplied format here is if you have non-premultiplied source data and are going to adjust the blend mode (see Cogl.Material.set_blend()) or use the data for something other than straight blending.
  • rowstride (int) – the memory offset in bytes between the starts of scanlines in data
  • data (int) – pointer the memory region where the source buffer resides
Returns:

A newly created Cogl.Texture or None on failure

Return type:

Cogl.Texture

Creates a new Cogl.Texture based on data residing in memory.

New in version 0.8.

Deprecated since version 1.18: Use specific constructors such as cogl_texture_2d_new_from_data()

classmethod new_from_file(filename, flags, internal_format)
Parameters:
  • filename (str) – the file to load
  • flags (Cogl.TextureFlags) – Optional flags for the texture, or Cogl.TextureFlags.NONE
  • internal_format (Cogl.PixelFormat) – the Cogl.PixelFormat to use for the GPU storage of the texture. If Cogl.PixelFormat.ANY is given then a premultiplied format similar to the format of the source data will be used. The default blending equations of Cogl expect premultiplied color data; the main use of passing a non-premultiplied format here is if you have non-premultiplied source data and are going to adjust the blend mode (see Cogl.Material.set_blend()) or use the data for something other than straight blending.
Raises:

GLib.Error

Returns:

A newly created Cogl.Texture or None on failure

Return type:

Cogl.Texture

Creates a Cogl.Texture from an image file.

New in version 0.8.

Deprecated since version 1.18: Use specific constructors such as cogl_texture_2d_new_from_file()

classmethod new_from_foreign(gl_handle, gl_target, width, height, x_pot_waste, y_pot_waste, format)
Parameters:
  • gl_handle (int) – opengl handle of foreign texture.
  • gl_target (int) – opengl target type of foreign texture
  • width (int) – width of foreign texture
  • height (int) – height of foreign texture.
  • x_pot_waste (int) – horizontal waste on the right hand edge of the texture.
  • y_pot_waste (int) – vertical waste on the bottom edge of the texture.
  • format (Cogl.PixelFormat) – format of the foreign texture.
Returns:

A newly created Cogl.Texture or None on failure

Return type:

Cogl.Texture

Creates a Cogl.Texture based on an existing OpenGL texture; the width, height and format are passed along since it is not always possible to query these from OpenGL.

The waste arguments allow you to create a Cogl texture that maps to a region smaller than the real OpenGL texture. For instance if your hardware only supports power-of-two textures you may load a non-power-of-two image into a larger power-of-two texture and use the waste arguments to tell Cogl which region should be mapped to the texture coordinate range [0:1].

New in version 0.8.

Deprecated since version 1.18: Use specific constructors such as cogl_texture_2d_new_from_foreign()

classmethod new_with_size(width, height, flags, internal_format)
Parameters:
Returns:

A newly created Cogl.Texture or None on failure

Return type:

Cogl.Texture

Creates a new Cogl.Texture with the specified dimensions and pixel format.

New in version 0.8.

Deprecated since version 1.18: Use specific constructors such as cogl_texture_2d_new_with_size()

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

new_from_sub_texture(sub_x, sub_y, sub_width, sub_height)
Parameters:
  • sub_x (int) – X coordinate of the top-left of the subregion
  • sub_y (int) – Y coordinate of the top-left of the subregion
  • sub_width (int) – Width in pixels of the subregion
  • sub_height (int) – Height in pixels of the subregion
Returns:

A newly created Cogl.Texture or None on failure

Return type:

Cogl.Texture

Creates a new texture which represents a subregion of another texture. The GL resources will be shared so that no new texture data is actually allocated.

Sub textures have undefined behaviour texture coordinates outside of the range [0,1] are used. They also do not work with CoglVertexBuffers.

The sub texture will keep a reference to the full texture so you do not need to keep one separately if you only want to use the sub texture.

New in version 1.2.

Deprecated since version 1.18: Use cogl_sub_texture_new()

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_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_texture_2d_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.