HildonRemoteTexture

HildonRemoteTexture — Clutter/GLES texture created from a shared memory area.

Synopsis

                    HildonRemoteTexture;
GtkWidget*          hildon_remote_texture_new           (void);
void                hildon_remote_texture_send_message  (HildonRemoteTexture *self,
                                                         guint32 message_type,
                                                         guint32 l0,
                                                         guint32 l1,
                                                         guint32 l2,
                                                         guint32 l3,
                                                         guint32 l4);
void                hildon_remote_texture_set_image     (HildonRemoteTexture *self,
                                                         key_t key,
                                                         guint width,
                                                         guint height,
                                                         guint bpp);
void                hildon_remote_texture_set_offset    (HildonRemoteTexture *self,
                                                         double x,
                                                         double y);
void                hildon_remote_texture_set_opacity   (HildonRemoteTexture *self,
                                                         gint opacity);
void                hildon_remote_texture_set_parent    (HildonRemoteTexture *self,
                                                         GtkWindow *parent);
void                hildon_remote_texture_set_position  (HildonRemoteTexture *self,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height);
void                hildon_remote_texture_set_scale     (HildonRemoteTexture *self,
                                                         double x_scale,
                                                         double y_scale);
void                hildon_remote_texture_set_show      (HildonRemoteTexture *self,
                                                         gint show);
void                hildon_remote_texture_set_show_full (HildonRemoteTexture *self,
                                                         gint show,
                                                         gint opacity);
void                hildon_remote_texture_update_area   (HildonRemoteTexture *self,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height);

Description

The HildonRemoteTexture is a GTK+ widget which allows the rendering of a shared memory area within hildon-desktop. It allows the memory area to be positioned and scaled, without altering its' contents.

Details

HildonRemoteTexture

typedef struct {
    GtkWindow parent;
} HildonRemoteTexture;


hildon_remote_texture_new ()

GtkWidget*          hildon_remote_texture_new           (void);

Creates a new HildonRemoteTexture.

Returns : A HildonRemoteTexture

Since 2.2


hildon_remote_texture_send_message ()

void                hildon_remote_texture_send_message  (HildonRemoteTexture *self,
                                                         guint32 message_type,
                                                         guint32 l0,
                                                         guint32 l1,
                                                         guint32 l2,
                                                         guint32 l3,
                                                         guint32 l4);

Sends an X11 ClientMessage event to the window manager with the specified parameters -- id (message_type) and data (l0, l1, l2, l3, l4).

This is an internal utility function that application will not need to call directly.

self : A HildonRemoteTexture
message_type : Message id for the remote texture message.
l0 : 1st remote texture message parameter.
l1 : 2nd remote texture message parameter.
l2 : 3rd remote texture message parameter.
l3 : 4th remote texture message parameter.
l4 : 5th remote texture message parameter.

Since 2.2


hildon_remote_texture_set_image ()

void                hildon_remote_texture_set_image     (HildonRemoteTexture *self,
                                                         key_t key,
                                                         guint width,
                                                         guint height,
                                                         guint bpp);

self : A HildonRemoteTexture
key : The key that would be used with shmget in hildon-desktop. The key should probably be created with ftok, and the relevant shared memory area should be created before this call.
width : width of image in pixels
height : height of image in pixels
bpp : BYTES per pixel - usually 2,3 or 4

Since 2.2


hildon_remote_texture_set_offset ()

void                hildon_remote_texture_set_offset    (HildonRemoteTexture *self,
                                                         double x,
                                                         double y);

Send a message to the window manager setting the offset of the remote texture in the window (in Remote texture's pixels). The texture is also subject to the animation effects rendered by the compositing window manager on that window (like those by task switcher).

If the remote texture WM-counterpart is not ready, the show message will be queued until the WM is ready for it.

self : A HildonRemoteTexture
x : Desired X offset
y : Desired Y offset

Since 2.2


hildon_remote_texture_set_opacity ()

void                hildon_remote_texture_set_opacity   (HildonRemoteTexture *self,
                                                         gint opacity);

This function is a shortcut for hildon_remote_texture_set_show_full(), setting actor opacity without changing it's overall visibility.

See hildon_remote_texture_set_show_full() for description of the range of values opacity argument takes.

self : A HildonRemoteTexture
opacity : Desired opacity setting

Since 2.2


hildon_remote_texture_set_parent ()

void                hildon_remote_texture_set_parent    (HildonRemoteTexture *self,
                                                         GtkWindow *parent);

Send a message to the window manager setting the parent window for the remote texture. Parenting an actor will not affect the X window that the HildonRemoteTexture represents, but it's off-screen bitmap as it is handled by the compositing window manager.

Parenting an remote texture will affect its visibility as set by the gtk_widget_show(), gtk_widget_hide() and hildon_remote_texture_set_show(). The remote texture will only be visible when the top-level window it is parented is visible.

Passing NULL as a parent argument will unparent the remote texture. This will restore the actor's visibility if it was suppressed by being unparented or parented to an unmapped window.

If the remote texture WM-counterpart is not ready, the show message will be queued until the WM is ready for it.

self : A HildonRemoteTexture
parent : A GtkWindow that the actor will be parented to.

Since 2.2


hildon_remote_texture_set_position ()

void                hildon_remote_texture_set_position  (HildonRemoteTexture *self,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height);

Send a message to the window manager setting the offset of the remote texture in the window (in Remote texture's pixels). The texture is also subject to the animation effects rendered by the compositing window manager on that window (like those by task switcher).

If the remote texture WM-counterpart is not ready, the show message will be queued until the WM is ready for it.

self : A HildonRemoteTexture
x : Desired X coordinate
y : Desired Y coordinate
width : Desired width
height : Desired height

Since 2.2


hildon_remote_texture_set_scale ()

void                hildon_remote_texture_set_scale     (HildonRemoteTexture *self,
                                                         double x_scale,
                                                         double y_scale);

self :
x_scale :
y_scale :

hildon_remote_texture_set_show ()

void                hildon_remote_texture_set_show      (HildonRemoteTexture *self,
                                                         gint show);

This function is a shortcut for hildon_remote_texture_set_show_full(), setting the overall actor visibility without changing it's opacity setting.

self : A HildonRemoteTexture
show : A boolean flag setting the visibility of the remote texture.

Since 2.2


hildon_remote_texture_set_show_full ()

void                hildon_remote_texture_set_show_full (HildonRemoteTexture *self,
                                                         gint show,
                                                         gint opacity);

Send a message to the window manager setting the visibility of the remote texture. This will only affect the visibility of the remote texture set by the compositing window manager in its own rendering pipeline, after X has drawn the window to the off-screen buffer. This setting, naturally, has no effect if the HildonRemoteTexture widget is not visible in X11 terms (i.e. realized and mapped).

Furthermore, if a widget is parented, its final visibility will be affected by that of the parent window.

The opacity setting ranges from zero (0), being completely transparent to 255 (0xff) being fully opaque.

If the remote texture WM-counterpart is not ready, the show message will be queued until the WM is ready for it.

self : A HildonRemoteTexture
show : A boolean flag setting the visibility of the remote texture.
opacity : Desired opacity setting

Since 2.2


hildon_remote_texture_update_area ()

void                hildon_remote_texture_update_area   (HildonRemoteTexture *self,
                                                         gint x,
                                                         gint y,
                                                         gint width,
                                                         gint height);

This signals to hildon-desktop that a specific region of the memory area has changed. This will trigger a redraw and will update the relevant tiles of the texture.

self : A HildonRemoteTexture
x : offset of damaged area in pixels
y : offset of damaged area in pixels
width : width of damaged area in pixels
height : height of damaged area in pixels

Since 2.2