Display Channel

Display Channel — remote display area

Stability Level

Stable, unless otherwise indicated

Functions

Properties

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

Signals

void display-invalidate Run First
void display-mark Run First
void display-primary-create Run First
void display-primary-destroy Run First
void gl-draw  
gboolean gst-video-overlay  
gpointer streaming-mode  

Types and Values

Object Hierarchy

    GBoxed
    ╰── SpiceGlScanout
    GObject
    ╰── SpiceChannel
        ╰── SpiceDisplayChannel

Includes

#include <spice-client.h>

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.

Functions

spice_display_get_gl_scanout ()

const SpiceGlScanout *
spice_display_get_gl_scanout (SpiceDisplayChannel *channel);

spice_display_get_gl_scanout has been deprecated since version 0.35 and should not be used in newly-written code.

use spice_display_channel_get_gl_scanout() instead.

Retrieves the GL scanout if available

Parameters

channel

a SpiceDisplayChannel

 

Returns

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

Since: 0.31


spice_display_channel_get_gl_scanout ()

const SpiceGlScanout *
spice_display_channel_get_gl_scanout (SpiceDisplayChannel *channel);

Retrieves the GL scanout if available

Parameters

channel

a SpiceDisplayChannel

 

Returns

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

Since: 0.35


spice_display_gl_draw_done ()

void
spice_display_gl_draw_done (SpiceDisplayChannel *channel);

spice_display_gl_draw_done has been deprecated since version 0.35 and should not be used in newly-written code.

use spice_display_channel_gl_draw_done() instead.

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

Parameters

channel

a SpiceDisplayChannel

 

Since: 0.31


spice_display_channel_gl_draw_done ()

void
spice_display_channel_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).

Parameters

channel

a SpiceDisplayChannel

 

Since: 0.35


spice_display_get_primary ()

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

spice_display_get_primary has been deprecated since version 0.35 and should not be used in newly-written code.

use spice_display_channel_get_primary() instead.

Retrieve primary display surface surface_id .

Parameters

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_channel_get_primary ()

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

Retrieve primary display surface surface_id .

Parameters

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 .

Since: 0.35


spice_display_change_preferred_compression ()

void
spice_display_change_preferred_compression
                               (SpiceChannel *channel,
                                gint compression);

spice_display_change_preferred_compression has been deprecated since version 0.35 and should not be used in newly-written code.

use spice_display_channel_change_preferred_compression() instead.

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

Parameters

channel

a SpiceDisplayChannel

 

compression

a SpiceImageCompression

 

Since: 0.31


spice_display_channel_change_preferred_compression ()

void
spice_display_channel_change_preferred_compression
                               (SpiceChannel *channel,
                                gint compression);

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

Parameters

channel

a SpiceDisplayChannel

 

compression

a SpiceImageCompression

 

Since: 0.35


spice_display_change_preferred_video_codec_type ()

void
spice_display_change_preferred_video_codec_type
                               (SpiceChannel *channel,
                                gint codec_type);

spice_display_change_preferred_video_codec_type has been deprecated since version 0.35 and should not be used in newly-written code.

use spice_display_channel_change_preferred_video_codec_type() instead.

Tells the spice server to change the preferred video codec type for streaming in channel . Application can set only one preferred video codec per display channel.

Parameters

channel

a SpiceDisplayChannel

 

codec_type

a SpiceVideoCodecType

 

Since: 0.34


spice_display_channel_change_preferred_video_codec_type ()

void
spice_display_channel_change_preferred_video_codec_type
                               (SpiceChannel *channel,
                                gint codec_type);

spice_display_channel_change_preferred_video_codec_type has been deprecated since version 0.38 and should not be used in newly-written code.

use spice_display_channel_change_preferred_video_codec_types() instead.

Tells the spice server to change the preferred video codec type for streaming in channel . Application can set only one preferred video codec per display channel.

Parameters

channel

a SpiceDisplayChannel

 

codec_type

a SpiceVideoCodecType

 

Since: 0.35


spice_display_channel_change_preferred_video_codec_types ()

gboolean
spice_display_channel_change_preferred_video_codec_types
                               (SpiceChannel *channel,
                                const gint *codecs,
                                gsize ncodecs,
                                GError **err);

spice_gl_scanout_free ()

void
spice_gl_scanout_free (SpiceGlScanout *scanout);

Frees the scanout .

Parameters

scanout

a SpiceGlScanout

 

Since: 0.31

Types and Values

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.

Members

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.

Members

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.

Members

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.

Members

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

 

Property Details

The “gl-scanout” property

  “gl-scanout”               SpiceGlScanout *

The last SpiceGlScanout received.

Flags: Read

Since: 0.31


The “height” property

  “height”                   guint

The primary surface height.

Flags: Read

Default value: 0


The “monitors” property

  “monitors”                 GArray *

Current monitors configuration.

Flags: Read

Since: 0.13


The “monitors-max” property

  “monitors-max”             guint

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

Flags: Read

Allowed values: [1,256]

Default value: 1

Since: 0.13


The “width” property

  “width”                    guint

The primary surface width.

Flags: Read

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)

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

Parameters

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.

 

Flags: Run First


The “display-mark” signal

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

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

Parameters

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.

 

Flags: Run First


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)

The “display-primary-create” signal provides main display buffer data.

Parameters

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.

 

Flags: Run First


The “display-primary-destroy” signal

void
user_function (SpiceDisplayChannel *display,
               gpointer             user_data)

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

Parameters

display

the SpiceDisplayChannel that emitted the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run First


The “gl-draw” signal

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

The “gl-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.

Parameters

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


The “gst-video-overlay” signal

gboolean
user_function (SpiceDisplayChannel *display,
               GstPipeline         *pipeline,
               gpointer             user_data)

The “gst-video-overlay” signal is emitted when pipeline is ready and can be passed to widget to register GStreamer overlay interface and other GStreamer callbacks. If the pipeline pointer is NULL, the drawing area of the native renderer is set visible.

Parameters

display

the SpiceDisplayChannel that emitted the signal

 

pipeline

pointer to GStreamer's pipeline

 

user_data

user data set when the signal handler was connected.

 

Returns

TRUE if the overlay is being set

Since: 0.36


The “streaming-mode” signal

gpointer
user_function (SpiceDisplayChannel *display,
               gboolean             streaming_mode,
               gpointer             user_data)

Return: handle for the display window if possible

The “streaming-mode” signal is emitted when spice server is working in streaming mode.

SpiceDisplayChannel::streaming-mode has been deprecated since version 0.36 and should not be used in newly-written code.

use “gst-video-overlay” instead

Parameters

display

the SpiceDisplayChannel that emitted the signal

 

streaming_mode

TRUE when it's streaming mode

 

user_data

user data set when the signal handler was connected.

 

Since: 0.35

See Also

SpiceChannel, and the GTK widget SpiceDisplay