Cairo GL

---

Cairo GL/Evas_GL APIs are official APIs for Tizen.

Required Header

#include <cairo-evas-gl.h>

Overview

In Tizen, Cairo provides gl backend in order to do hardware-accelerated rendering. Since the EGL is not public supported in Tizen, Cairo Evas_GL has been provided to user interfaces instead to allow indirect access to EGL layer.

Features :

• Support a new cairo_device structure for interface to the underlying GL or EvasGL.
  
• Support a new cairo_surface structure for representing GL or Evas_GL_Surface object that cairo can render to.
  
• Get the underlying Evas_GL object used to create cairo device object.
  
• Get the underlying Evas_GL_Context object used to create cairo device object.

Remarks :

• Cairo GL and Cairo Evas_GL will use an GL/Evas_GL context and API set.
  
• Therefore, Evas_GL and OpenGL-ES should be provided for normal operation of Cairo gl backend.
  

Functions
cairo_public cairo_surface_t *	cairo_gl_surface_create (cairo_device_t *device, cairo_content_t content, int width, int height)
	Create a cairo GL surface using the device as the underlying rendering system.
cairo_public cairo_surface_t *	cairo_gl_surface_create_for_texture (cairo_device_t *abstract_device, cairo_content_t content, unsigned int tex, int width, int height)
	Create a cairo GL surface using the texture as the render target, and the device as the underlying rendering system. The content must match the format of the texture CAIRO_CONTENT_ALPHA <-> GL_ALPHA CAIRO_CONTENT_COLOR <-> GL_RGB/GL_BGR CAIRO_CONTENT_COLOR_ALPHA <-> GL_RGBA/GL_BGRA .
cairo_public int	cairo_gl_surface_get_width (cairo_surface_t *abstract_surface)
	Returns the width of given cairo surface object.
cairo_public int	cairo_gl_surface_get_height (cairo_surface_t *abstract_surface)
	Returns the height of given cairo surface object.
cairo_public void	cairo_gl_device_set_thread_aware (cairo_device_t *device, cairo_bool_t thread_aware)
	Cairo can be used in multithreaded environment. By default, cairo switches out the current GL context after each draw finishes. This API tells cairo not to switch GL context if no other thread uses cairo for rendering. In carefully designed application, there should be a single, dedicated rendering thread. .
cairo_public cairo_device_t *	cairo_evas_gl_device_create (Evas_GL *evas_gl, Evas_GL_Context *evas_context)
	Creates and returns a new cairo_device structure for interface to underlying rendering system.
cairo_public cairo_surface_t *	cairo_gl_surface_create_for_evas_gl (cairo_device_t *device, Evas_GL_Surface *evas_surface, Evas_GL_Config *evas_config, int width, int height)
	Creates and returns a new cairo_surface structure for representing Evas_GL_Surface object that cairo can render to.
cairo_public Evas_GL *	cairo_evas_gl_device_get_gl (cairo_device_t *device)
	Returns the underlying Evas_GL object used to create cairo device object.
cairo_public Evas_GL_Context *	cairo_evas_gl_device_get_context (cairo_device_t *device)
	Returns the underlying Evas_GL_Context object used to create cairo device object.

---

Function Documentation

cairo_public cairo_device_t* cairo_evas_gl_device_create	(	Evas_GL *	evas_gl,
		Evas_GL_Context *	evas_context
	)

Creates and returns a new cairo_device structure for interface to underlying rendering system.

Since :

2.3.1

Parameters:

[in]	evas_gl	The given Evas_gl object
[in]	evas_context	The given Evas GL Context object

Returns:

The created cairo_device structure, or an error status on failure. The error value can be retrieved with cairo_device_status().

See also:

evas_gl_new

evas_gl_context_create

cairo_gl_surface_create_for_evas_gl

cairo_public Evas_GL_Context* cairo_evas_gl_device_get_context

(

cairo_device_t *

device

)

Returns the underlying Evas_GL_Context object used to create cairo device object.

Since :

2.3.1

Parameters:

[in]

device

The given cairo_device_t represents the driver interface to underlying rendering system

Returns:

The created Evas_GL_Context object or NULL on failure The error value on failure can be retrieved with cairo_status().

cairo_public Evas_GL* cairo_evas_gl_device_get_gl

(

cairo_device_t *

device

)

Returns the underlying Evas_GL object used to create cairo device object.

Since :

2.3.1

Parameters:

[in]

device

The given cairo_device_t represents the driver interface to underlying rendering system

Returns:

The created Evas_GL object or NULL on failure The error value on failure can be retrieved with cairo_status().

cairo_public void cairo_gl_device_set_thread_aware	(	cairo_device_t *	device,
		cairo_bool_t	thread_aware
	)

Cairo can be used in multithreaded environment.
By default, cairo switches out the current GL context after each draw finishes.
This API tells cairo not to switch GL context if no other thread uses cairo for rendering.
In carefully designed application, there should be a single, dedicated rendering thread.
.

Since :

2.3.1

Parameters:

[in]	device	The given cairo_device structure for the interface to underlying rendering system
[in]	thread_aware	Set this value as FALSE to choose non-thread-aware mode

cairo_public cairo_surface_t* cairo_gl_surface_create	(	cairo_device_t *	device,
		cairo_content_t	content,
		int	width,
		int	height
	)

Create a cairo GL surface using the device as the underlying rendering system.

Since :

2.3.1

Parameters:

[in]	device	The given cairo_device_t represents the driver interface to underlying rendering system
[in]	content	Type of content in the surface
[in]	width	Width of the surface, in pixels
[in]	height	Height of the surface, in pixels

Returns:

The created surface or NULL on failure The error value on failure can be retrieved with cairo_status().

cairo_public cairo_surface_t* cairo_gl_surface_create_for_evas_gl	(	cairo_device_t *	device,
		Evas_GL_Surface *	evas_surface,
		Evas_GL_Config *	evas_config,
		int	width,
		int	height
	)

Creates and returns a new cairo_surface structure for representing Evas_GL_Surface object that cairo can render to.

Since :

2.3.1

Parameters:

[in]	device	The given cairo_device structure for the interface to underlying rendering system
[in]	evas_surface	The given Evas_GL_Surface object for GL Rendering
[in]	evas_config	The pixel format and configuration of the rendering surface
[in]	width	The width of the surface
[in]	height	The height of the surface

Returns:

The created cairo_surface structure, or an error status on failure The error value can be retrieved with cairo_surface_status().

See also:

cairo_evas_gl_device_create

evas_gl_surface_create

evas_gl_config_new

cairo_public cairo_surface_t* cairo_gl_surface_create_for_texture	(	cairo_device_t *	abstract_device,
		cairo_content_t	content,
		unsigned int	tex,
		int	width,
		int	height
	)

Create a cairo GL surface using the texture as the render target, and the device as the underlying rendering system.
The content must match the format of the texture
CAIRO_CONTENT_ALPHA <-> GL_ALPHA
CAIRO_CONTENT_COLOR <-> GL_RGB/GL_BGR
CAIRO_CONTENT_COLOR_ALPHA <-> GL_RGBA/GL_BGRA
.

Since :

2.3.1

Parameters:

[in]	abstract_device	The given cairo_device_t represents the driver interface to underlying rendering system
[in]	content	Type of content in the surface
[in]	tex	Name of texture to use for storage of surface pixels
[in]	width	Width of the surface, in pixels
[in]	height	Height of the surface, in pixels

Returns:

The created surface or NULL on failure The error value on failure can be retrieved with cairo_status().

cairo_public int cairo_gl_surface_get_height

(

cairo_surface_t *

abstract_surface

)

Returns the height of given cairo surface object.

Since :

2.3.1

Parameters:

[in]

abstract_surface

The given cairo_surface_t object

Returns:

the surface height or NULL on failure The error value on failure can be retrieved with cairo_status().

cairo_public int cairo_gl_surface_get_width

(

cairo_surface_t *

abstract_surface

)

Returns the width of given cairo surface object.

Since :

2.3.1

Parameters:

[in]

abstract_surface

The given cairo_surface_t object

Returns:

the surface width or NULL on failure The error value on failure can be retrieved with cairo_status().