Display Channel

Display Channel — remote display area

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <spice-client.h>

struct              SpiceDisplayChannel;
struct              SpiceDisplayChannelClass;
struct              SpiceDisplayMonitorConfig;
struct              SpiceDisplayPrimary;
struct              SpiceGlScanout;

const SpiceGlScanout * spice_display_get_gl_scanout     (SpiceDisplayChannel *channel);
void                spice_display_gl_draw_done          (SpiceDisplayChannel *channel);
gboolean            spice_display_get_primary           (SpiceChannel *channel,
                                                         guint32 surface_id,
                                                         SpiceDisplayPrimary *primary);
void                spice_display_change_preferred_compression
                                                        (SpiceChannel *channel,
                                                         gint compression);
void                spice_gl_scanout_free               (SpiceGlScanout *scanout);

Object Hierarchy

  GObject
   +----SpiceChannel
         +----SpiceDisplayChannel
  GBoxed
   +----SpiceGlScanout

Properties

  "gl-scanout"               SpiceGlScanout*       : Read
  "height"                   guint                 : Read
  "monitors"                 GArray*               : Read
  "monitors-max"             guint                 : Read
  "width"                    guint                 : Read

Signals

  "display-invalidate"                             : Run First
  "display-mark"                                   : Run First
  "display-primary-create"                         : Run First
  "display-primary-destroy"                        : Run First
  "gl-draw"                                        

Description

A class that handles the rendering of the remote display and inform of its updates.

The creation of the main graphic buffer is signaled with "display-primary-create".

The update of regions is notified by "display-invalidate" signals.

Details

struct SpiceDisplayChannel

struct SpiceDisplayChannel;

The SpiceDisplayChannel struct is opaque and should not be accessed directly.


struct SpiceDisplayChannelClass

struct SpiceDisplayChannelClass {
    SpiceChannelClass parent_class;

    /* signals */
    void (*display_primary_create)(SpiceChannel *channel, gint format,
                                   gint width, gint height, gint stride,
                                   gint shmid, gpointer data);
    void (*display_primary_destroy)(SpiceChannel *channel);
    void (*display_invalidate)(SpiceChannel *channel,
                               gint x, gint y, gint w, gint h);
    void (*display_mark)(SpiceChannel *channel,
                         gboolean mark);
};

Class structure for SpiceDisplayChannel.

SpiceChannelClass parent_class;

Parent class.

display_primary_create ()

Signal class handler for the "display-primary-create" signal.

display_primary_destroy ()

Signal class handler for the "display-primary-destroy" signal.

display_invalidate ()

Signal class handler for the "display-invalidate" signal.

display_mark ()

Signal class handler for the "display-mark" signal.

struct SpiceDisplayMonitorConfig

struct SpiceDisplayMonitorConfig {
    guint id;
    guint surface_id;
    guint x;
    guint y;
    guint width;
    guint height;
};

Holds a monitor configuration.

guint id;

monitor id

guint surface_id;

monitor surface id

guint x;

x position of the monitor

guint y;

y position of the monitor

guint width;

width of the monitor

guint height;

height of the monitor

struct SpiceDisplayPrimary

struct SpiceDisplayPrimary {
    enum SpiceSurfaceFmt format;
    gint width;
    gint height;
    gint stride;
    gint shmid;
    guint8 *data;
    gboolean marked;
};

Holds the information necessary to use the primary surface.

enum SpiceSurfaceFmt format;

primary buffer format

gint width;

width of the primary

gint height;

height of the primary

gint stride;

stride of the primary

gint shmid;

identifier of the shared memory segment associated with the data, or -1 if not shm

guint8 *data;

pointer to primary buffer

gboolean marked;

whether the display is marked ready

struct SpiceGlScanout

struct SpiceGlScanout {
    gint fd;
    guint32 width;
    guint32 height;
    guint32 stride;
    guint32 format;
    gboolean y0top;
};

Holds the information necessary for using the GL display scanout.

gint fd;

a drm DMABUF file that can be imported with eglCreateImageKHR

guint32 width;

width of the scanout

guint32 height;

height of the scanout

guint32 stride;

stride of the scanout

guint32 format;

the drm fourcc format

gboolean y0top;

orientation of the scanout

spice_display_get_gl_scanout ()

const SpiceGlScanout * spice_display_get_gl_scanout     (SpiceDisplayChannel *channel);

Retrieves the GL scanout if available

channel :

a SpiceDisplayChannel

Returns :

the current GL scanout, or NULL if none or not valid

Since 0.31


spice_display_gl_draw_done ()

void                spice_display_gl_draw_done          (SpiceDisplayChannel *channel);

After a SpiceDisplayChannel::gl-draw is emitted, the client should draw the current display with the current GL scanout, and must release the GL resource with a call to spice_display_gl_draw_done() (failing to do so for each gl-draw may result in a frozen display).

channel :

a SpiceDisplayChannel

Since 0.31


spice_display_get_primary ()

gboolean            spice_display_get_primary           (SpiceChannel *channel,
                                                         guint32 surface_id,
                                                         SpiceDisplayPrimary *primary);

Retrieve primary display surface surface_id.

channel :

a SpiceDisplayChannel

surface_id :

a surface id

primary :

a SpiceDisplayPrimary

Returns :

TRUE if the primary surface was found and its details collected in primary.

spice_display_change_preferred_compression ()

void                spice_display_change_preferred_compression
                                                        (SpiceChannel *channel,
                                                         gint compression);

Tells the spice server to change the preferred image compression for the channel.

channel :

a SpiceDisplayChannel

compression :

a SpiceImageCompression

Since 0.31


spice_gl_scanout_free ()

void                spice_gl_scanout_free               (SpiceGlScanout *scanout);

Property Details

The "gl-scanout" property

  "gl-scanout"               SpiceGlScanout*       : Read

The last SpiceGlScanout received.

Since 0.31


The "height" property

  "height"                   guint                 : Read

The primary surface height.

Default value: 0


The "monitors" property

  "monitors"                 GArray*               : Read

Current monitors configuration.

Since 0.13


The "monitors-max" property

  "monitors-max"             guint                 : Read

The maximum number of monitors the server or guest supports. May change during client lifetime, for instance guest may reboot or dynamically adjust this.

Allowed values: [1,256]

Default value: 1

Since 0.13


The "width" property

  "width"                    guint                 : Read

The primary surface width.

Default value: 0

Signal Details

The "display-invalidate" signal

void                user_function                      (SpiceDisplayChannel *display,
                                                        gint                 x,
                                                        gint                 y,
                                                        gint                 width,
                                                        gint                 height,
                                                        gpointer             user_data)      : Run First

The "display-invalidate" signal is emitted when the rectangular region x/y/w/h of the primary buffer is updated.

display :

the SpiceDisplayChannel that emitted the signal

x :

x position

y :

y position

width :

width

height :

height

user_data :

user data set when the signal handler was connected.

The "display-mark" signal

void                user_function                      (SpiceDisplayChannel *display,
                                                        gint                 mark,
                                                        gpointer             user_data)      : Run First

The "display-mark" signal is emitted when the RED_DISPLAY_MARK command is received, and the display should be exposed.

display :

the SpiceDisplayChannel that emitted the signal

mark :

TRUE when the display mark has been received

user_data :

user data set when the signal handler was connected.

The "display-primary-create" signal

void                user_function                      (SpiceDisplayChannel *display,
                                                        gint                 format,
                                                        gint                 width,
                                                        gint                 height,
                                                        gint                 stride,
                                                        gint                 shmid,
                                                        gpointer             imgdata,
                                                        gpointer             user_data)      : Run First

The "display-primary-create" signal provides main display buffer data.

display :

the SpiceDisplayChannel that emitted the signal

format :

SPICE_SURFACE_FMT_32_xRGB or SPICE_SURFACE_FMT_16_555;

width :

width resolution

height :

height resolution

stride :

the buffer stride ("width" padding)

shmid :

identifier of the shared memory segment associated with the imgdata, or -1 if not shm

imgdata :

pointer to surface buffer

user_data :

user data set when the signal handler was connected.

The "display-primary-destroy" signal

void                user_function                      (SpiceDisplayChannel *display,
                                                        gpointer             user_data)      : Run First

The "display-primary-destroy" signal is emitted when the primary surface is freed and should not be accessed anymore.

display :

the SpiceDisplayChannel that emitted the signal

user_data :

user data set when the signal handler was connected.

The "gl-draw" signal

void                user_function                      (SpiceDisplayChannel *display,
                                                        guint                x,
                                                        guint                y,
                                                        guint                width,
                                                        guint                height,
                                                        gpointer             user_data)

The "draw" signal is emitted when the rectangular region x/y/w/h of the GL scanout is updated and must be drawn. When the draw is finished, you must call spice_display_gl_draw_done() in order to release the GL resources.

display :

the SpiceDisplayChannel that emitted the signal

x :

x position

y :

y position

width :

width

height :

height

user_data :

user data set when the signal handler was connected.

Since 0.31

See Also

SpiceChannel, and the GTK widget SpiceDisplay