Display Channel: Spice-GTK Reference Manual

## Display Channel

Display Channel — remote display area

## Stability Level

Stable, unless otherwise indicated

## Functions

const SpiceGlScanout * | spice_display_get_gl_scanout ()
const SpiceGlScanout * | spice_display_channel_get_gl_scanout ()
void | spice_display_gl_draw_done ()
void | spice_display_channel_gl_draw_done ()
gboolean | spice_display_get_primary ()
gboolean | spice_display_channel_get_primary ()
void | spice_display_change_preferred_compression ()
void | spice_display_channel_change_preferred_compression ()
void | spice_display_change_preferred_video_codec_type ()
void | spice_display_channel_change_preferred_video_codec_type ()
gboolean | spice_display_channel_change_preferred_video_codec_types ()
void | spice_gl_scanout_free ()

## 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

struct | SpiceDisplayChannel
struct | SpiceDisplayChannelClass
struct | SpiceDisplayMonitorConfig
struct | SpiceDisplayPrimary
struct | SpiceGlScanout

## 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` .

[method]

#### Parameters

channel | a SpiceDisplayChannel. | [type 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` .

[method]

#### Parameters

channel | a SpiceDisplayChannel. | [type 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` .

[method]

#### Parameters

channel | a SpiceDisplayChannel. | [type 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` .

[method]

#### Parameters

channel | a SpiceDisplayChannel. | [type 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.

[method]

#### Parameters

channel | a SpiceDisplayChannel. | [type 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.

[method]

#### Parameters

channel | a SpiceDisplayChannel. | [type 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);

Tells the spice server the ordered preferred video codec types to use for streaming in `channel` .

[method]

#### Parameters

channel | a SpiceDisplayChannel. | [type SpiceDisplayChannel]
codecs | an array of `ncodecs` SpiceVideoCodecType types. | [array length=ncodecs]
ncodecs | the number of codec types in the `codecs` array |
err | GError describing the reason why the change failed |

#### Returns

`TRUE` if the preferred codec list was successfully changed, and `FALSE` otherwise.

Since: 0.38

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

Owner: SpiceDisplayChannel

Flags: Read

Since: 0.31

### The `“height”` property

      “height”                   guint

The primary surface height.

Owner: SpiceDisplayChannel

Flags: Read

Default value: 0

### The `“monitors”` property

      “monitors”                 GArray *

Current monitors configuration.

[type GArray(SpiceDisplayMonitorConfig)]

Owner: SpiceDisplayChannel

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.

Owner: SpiceDisplayChannel

Flags: Read

Allowed values: [1,256]

Default value: 1

Since: 0.13

### The `“width”` property

      “width”                    guint

The primary surface width.

Owner: SpiceDisplayChannel

Flags: Read

Default value: 0

## Signal Details

### The `“display-invalidate”` signal

    void
    user_function (SpiceDisplayChannel *display,
                   int                  x,
                   int                  y,
                   int                  width,
                   int                  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,
                   int                  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,
                   int                  format,
                   int                  width,
                   int                  height,
                   int                  stride,
                   int                  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