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

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

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

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

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