Functions to manipulate subsurfaces.
Ecore » Ecore_Wl2 - Wayland integration

Functions to manipulate wayland subsurfaces, using Ecore_Wl2_Subsurface. More...

## Functions

EAPI Ecore_Wl2_Subsurface * | ecore_wl2_subsurface_new (Ecore_Wl2_Window *window)
| Create and return a new subsurface.
EAPI void | ecore_wl2_subsurface_del (Ecore_Wl2_Subsurface *subsurface)
| Destroy the given subsurface, as well as the surface associated with it.
EAPI struct wl_surface * | ecore_wl2_subsurface_surface_get (Ecore_Wl2_Subsurface *subsurface)
| Get the wl_surface for this subsurface.
EAPI void | ecore_wl2_subsurface_position_set (Ecore_Wl2_Subsurface *subsurface, int x, int y)
| Set the position of this subsurface, relative to its parent surface.
EAPI void | ecore_wl2_subsurface_position_get (Ecore_Wl2_Subsurface *subsurface, int *x, int *y)
| Get the position of this subsurface, relative to its parent surface.
EAPI void | ecore_wl2_subsurface_place_above (Ecore_Wl2_Subsurface *subsurface, struct wl_surface *surface)
| Place subsurface on layer above a reference surface.
EAPI void | ecore_wl2_subsurface_place_below (Ecore_Wl2_Subsurface *subsurface, struct wl_surface *surface)
| Place subsurface on layer below a reference surface.
EAPI void | ecore_wl2_subsurface_sync_set (Ecore_Wl2_Subsurface *subsurface, Eina_Bool sync)
| Enables or disables sub-surface synchronization.
EAPI void | ecore_wl2_subsurface_opaque_region_set (Ecore_Wl2_Subsurface *subsurface, int x, int y, int w, int h)
| Set an opaque region for the given subsurface.

## Detailed Description

Functions to manipulate wayland subsurfaces, using Ecore_Wl2_Subsurface.

This API is intended to expose Wayland subsurface functionality, although it should not be necessary for most applications to use it, as soon as we have means to make Evas automatically switch Evas images to use subsurfaces.

It can/should be used, for instance, when subsurfaces are needed to be not in sync with the main window surface.

## Function Documentation

## ecore_wl2_subsurface_new()

EAPI Ecore_Wl2_Subsurface * ecore_wl2_subsurface_new | ( | Ecore_Wl2_Window * | window | ) |

Create and return a new subsurface.

Create a new surface (and subsurface interface), with the parent surface being the one associated with the given window.

Parameters

  window | The window. It must be visible, otherwise there will be no surface created for it yet.

Returns
  the allocated and initialized Ecore_Wl2_Subsurface object, or NULL on failure

Since
  1.17

References eina_inlist_append(), EINA_INLIST_GET, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and ERR.

## ecore_wl2_subsurface_del()

EAPI void ecore_wl2_subsurface_del | ( | Ecore_Wl2_Subsurface * | subsurface | ) |

Destroy the given subsurface, as well as the surface associated with it.

Parameters

  subsurface | the subsurface

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN.

## ecore_wl2_subsurface_surface_get()

EAPI struct wl_surface * ecore_wl2_subsurface_surface_get | ( | Ecore_Wl2_Subsurface * | subsurface | ) |

Get the wl_surface for this subsurface.

Parameters

  subsurface | the subsurface

Returns
  the wl_surface associated with this subsurface, or NULL on failure

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## ecore_wl2_subsurface_position_set()

EAPI void ecore_wl2_subsurface_position_set | ( | Ecore_Wl2_Subsurface * | subsurface,
|  | int | x,
|  | int | y )

Set the position of this subsurface, relative to its parent surface.

If subsurface is defined and the x, y coordinates differ from the currently tracked position, this also schedules a sub-surface position change.

Parameters

  subsurface | the subsurface
  x | coordinate in the parent surface
  y | coordinate in the parent surface

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN.

## ecore_wl2_subsurface_position_get()

EAPI void ecore_wl2_subsurface_position_get | ( | Ecore_Wl2_Subsurface * | subsurface,
|  | int * | x,
|  | int * | y )

Get the position of this subsurface, relative to its parent surface.

Coordinates will be returned in x and y if non-NULL.

Parameters

  subsurface | the subsurface
  x | coordinate in the parent surface, or NULL to ignore
  y | coordinate in the parent surface, or NULL to ignore

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN.

## ecore_wl2_subsurface_place_above()

EAPI void ecore_wl2_subsurface_place_above | ( | Ecore_Wl2_Subsurface * | subsurface,
|  | struct wl_surface * | surface )

Place subsurface on layer above a reference surface.

Moves the subsurface to just above the reference surface, changing the z-order. The reference surface must be either a sibling or parent surface, else a protocol error will be generated.

Parameters

  subsurface | the subsurface
  surface | the sibling reference surface

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN.

## ecore_wl2_subsurface_place_below()

EAPI void ecore_wl2_subsurface_place_below | ( | Ecore_Wl2_Subsurface * | subsurface,
|  | struct wl_surface * | surface )

Place subsurface on layer below a reference surface.

See ecore_wl2_subsurface_place_above.

Parameters

  subsurface | the subsurface
  surface | the sibling reference surface

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN.

## ecore_wl2_subsurface_sync_set()

EAPI void ecore_wl2_subsurface_sync_set | ( | Ecore_Wl2_Subsurface * | subsurface,
|  | Eina_Bool | sync )

Enables or disables sub-surface synchronization.

When synchronization is enabled, surface commits on the subsurface will be cached and only applied when the parent surface's state is applied. This ensures atomic updates of the parent and all of its synchronized sub-surfaces.

When synchronization is disabled, commits will apply to the pending state directly without caching, just like a normal wl_surface. If there are already cached events when this is set, those events are applied simultaneously with the desync event.

Attempting to enable synchronization when the subsurface already thinks it's sync'd, or desync when it believes its desync'd, will be trivially ignored and will not generate a Wayland event.

See Wayland's set_desync documentation for further details and exceptional cases.

Parameters

  subsurface | the subsurface
  sync | true to enable synchronization, false to desynchronize

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN.

## ecore_wl2_subsurface_opaque_region_set()

EAPI void ecore_wl2_subsurface_opaque_region_set | ( | Ecore_Wl2_Subsurface * | subsurface,
|  | int | x,
|  | int | y,
|  | int | w,
|  | int | h )

Set an opaque region for the given subsurface.

This is an optimization hint to the compositor to allow it avoid redrawing content unnecessarily. Note that marking transparent content as opaque will cause repaint artifacts.

Use a 0x0 region size to unset the opaque region.

Parameters

  subsurface | the subsurface
  x | coordinate in the parent surface
  y | coordinate in the parent surface
  w | width to set as opaque
  h | height to set as opaque

Since
  1.17

References EINA_SAFETY_ON_NULL_RETURN, and ERR.