display.h (12384B)
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20#ifndef GUACENC_DISPLAY_H 21#define GUACENC_DISPLAY_H 22 23#include "config.h" 24#include "buffer.h" 25#include "cursor.h" 26#include "image-stream.h" 27#include "layer.h" 28#include "video.h" 29 30#include <cairo/cairo.h> 31#include <guacamole/protocol.h> 32#include <guacamole/timestamp.h> 33 34/** 35 * The maximum number of buffers that the Guacamole video encoder will handle 36 * within a single Guacamole protocol dump. 37 */ 38#define GUACENC_DISPLAY_MAX_BUFFERS 4096 39 40/** 41 * The maximum number of layers that the Guacamole video encoder will handle 42 * within a single Guacamole protocol dump. 43 */ 44#define GUACENC_DISPLAY_MAX_LAYERS 64 45 46/** 47 * The maximum number of streams that the Guacamole video encoder will handle 48 * within a single Guacamole protocol dump. 49 */ 50#define GUACENC_DISPLAY_MAX_STREAMS 64 51 52/** 53 * The current state of the Guacamole video encoder's internal display. 54 */ 55typedef struct guacenc_display { 56 57 /** 58 * The current mouse cursor state. 59 */ 60 guacenc_cursor* cursor; 61 62 /** 63 * All currently-allocated buffers. The index of the buffer corresponds to 64 * its position within this array, where -1 is the 0th entry. If a buffer 65 * has not yet been allocated, or a buffer has been freed (due to a 66 * "dispose" instruction), its entry here will be NULL. 67 */ 68 guacenc_buffer* buffers[GUACENC_DISPLAY_MAX_BUFFERS]; 69 70 /** 71 * All currently-allocated layers. The index of the layer corresponds to 72 * its position within this array. If a layer has not yet been allocated, 73 * or a layer has been freed (due to a "dispose" instruction), its entry 74 * here will be NULL. 75 */ 76 guacenc_layer* layers[GUACENC_DISPLAY_MAX_LAYERS]; 77 78 /** 79 * All currently-allocated image streams. The index of the stream 80 * corresponds to its position within this array. If a stream has not yet 81 * been allocated, or a stream has been freed (due to an "end" 82 * instruction), its entry here will be NULL. 83 */ 84 guacenc_image_stream* image_streams[GUACENC_DISPLAY_MAX_STREAMS]; 85 86 /** 87 * The timestamp of the last sync instruction handled, or 0 if no sync has 88 * yet been read. 89 */ 90 guac_timestamp last_sync; 91 92 /** 93 * The video that this display is recording to. 94 */ 95 guacenc_video* output; 96 97} guacenc_display; 98 99/** 100 * Handles a received "sync" instruction having the given timestamp, flushing 101 * the current display to the in-progress video encoding. 102 * 103 * @param display 104 * The display to flush to the video encoding as a new frame. 105 * 106 * @param timestamp 107 * The timestamp of the new frame, as dictated by the "sync" instruction 108 * sent at the end of the frame. 109 * 110 * @return 111 * Zero if the frame was successfully written, non-zero if an error occurs. 112 */ 113int guacenc_display_sync(guacenc_display* display, guac_timestamp timestamp); 114 115/** 116 * Flattens the given display, rendering all child layers to the frame buffers 117 * of their parent layers. The frame buffer of the default layer of the display 118 * will thus contain the flattened, composited rendering of the entire display 119 * state after this function succeeds. The contents of the frame buffers of 120 * each layer are replaced by this function. 121 * 122 * @param display 123 * The display to flatten. 124 * 125 * @return 126 * Zero if the flatten operation succeeds, non-zero if an error occurs 127 * preventing proper rendering. 128 */ 129int guacenc_display_flatten(guacenc_display* display); 130 131/** 132 * Allocates a new Guacamole video encoder display. This display serves as the 133 * representation of encoding state, as well as the state of the Guacamole 134 * display as instructions are read and handled. 135 * 136 * @param path 137 * The full path to the file in which encoded video should be written. 138 * 139 * @param codec 140 * The name of the codec to use for the video encoding, as defined by 141 * ffmpeg / libavcodec. 142 * 143 * @param width 144 * The width of the desired video, in pixels. 145 * 146 * @param height 147 * The height of the desired video, in pixels. 148 * 149 * @param bitrate 150 * The desired overall bitrate of the resulting encoded video, in bits per 151 * second. 152 * 153 * @return 154 * The newly-allocated Guacamole video encoder display, or NULL if the 155 * display could not be allocated. 156 */ 157guacenc_display* guacenc_display_alloc(const char* path, const char* codec, 158 int width, int height, int bitrate); 159 160/** 161 * Frees all memory associated with the given Guacamole video encoder display, 162 * and finishes any underlying encoding process. If the given display is NULL, 163 * this function has no effect. 164 * 165 * @param display 166 * The Guacamole video encoder display to free, which may be NULL. 167 * 168 * @return 169 * Zero if the encoding process completed successfully, non-zero otherwise. 170 */ 171int guacenc_display_free(guacenc_display* display); 172 173/** 174 * Returns the layer having the given index. A new layer will be allocated if 175 * necessary. If the layer having the given index already exists, it will be 176 * returned. 177 * 178 * @param display 179 * The Guacamole video encoder display to retrieve the layer from. 180 * 181 * @param index 182 * The index of the layer to retrieve. All valid layer indices are 183 * non-negative. 184 * 185 * @return 186 * The layer having the given index, or NULL if the index is invalid or 187 * a new layer cannot be allocated. 188 */ 189guacenc_layer* guacenc_display_get_layer(guacenc_display* display, 190 int index); 191 192/** 193 * Returns the depth of a given layer in terms of parent layers. The layer 194 * depth is the number of layers above the given layer in hierarchy, where a 195 * layer without any parent (such as the default layer) has a depth of 0. 196 * 197 * @param layer 198 * The layer to check. 199 * 200 * @return 201 * The depth of the layer. 202 */ 203int guacenc_display_get_depth(guacenc_display* display, guacenc_layer* layer); 204 205/** 206 * Frees all resources associated with the layer having the given index. If 207 * the layer has not been allocated, this function has no effect. 208 * 209 * @param display 210 * The Guacamole video encoder display associated with the layer being 211 * freed. 212 * 213 * @param index 214 * The index of the layer to free. All valid layer indices are 215 * non-negative. 216 * 217 * @return 218 * Zero if the layer was successfully freed or was not allocated, non-zero 219 * if the layer could not be freed as the index was invalid. 220 */ 221int guacenc_display_free_layer(guacenc_display* display, int index); 222 223/** 224 * Returns the buffer having the given index. A new buffer will be allocated if 225 * necessary. If the buffer having the given index already exists, it will be 226 * returned. 227 * 228 * @param display 229 * The Guacamole video encoder display to retrieve the buffer from. 230 * 231 * @param index 232 * The index of the buffer to retrieve. All valid buffer indices are 233 * negative. 234 * 235 * @return 236 * The buffer having the given index, or NULL if the index is invalid or 237 * a new buffer cannot be allocated. 238 */ 239guacenc_buffer* guacenc_display_get_buffer(guacenc_display* display, 240 int index); 241 242/** 243 * Frees all resources associated with the buffer having the given index. If 244 * the buffer has not been allocated, this function has no effect. 245 * 246 * @param display 247 * The Guacamole video encoder display associated with the buffer being 248 * freed. 249 * 250 * @param index 251 * The index of the buffer to free. All valid buffer indices are negative. 252 * 253 * @return 254 * Zero if the buffer was successfully freed or was not allocated, non-zero 255 * if the buffer could not be freed as the index was invalid. 256 */ 257int guacenc_display_free_buffer(guacenc_display* display, int index); 258 259/** 260 * Returns the buffer associated with the layer or buffer having the given 261 * index. A new buffer or layer will be allocated if necessary. If the given 262 * index refers to a layer (is non-negative), the buffer underlying that layer 263 * will be returned. If the given index refers to a buffer (is negative), that 264 * buffer will be returned directly. 265 * 266 * @param display 267 * The Guacamole video encoder display to retrieve the buffer from. 268 * 269 * @param index 270 * The index of the buffer or layer whose associated buffer should be 271 * retrieved. 272 * 273 * @return 274 * The buffer associated with the buffer or layer having the given index, 275 * or NULL if the index is invalid. 276 */ 277guacenc_buffer* guacenc_display_get_related_buffer(guacenc_display* display, 278 int index); 279 280/** 281 * Creates a new image stream having the given index. If the stream having the 282 * given index already exists, it will be freed and replaced. If the mimetype 283 * specified is not supported, the image stream will still be allocated but 284 * will have no associated decoder (blobs send to that stream will have no 285 * effect). 286 * 287 * @param display 288 * The Guacamole video encoder display to associate with the 289 * newly-created image stream. 290 * 291 * @param index 292 * The index of the stream to create. All valid stream indices are 293 * non-negative. 294 * 295 * @param mask 296 * The Guacamole protocol compositing operation (channel mask) to apply 297 * when drawing the image. 298 * 299 * @param layer_index 300 * The index of the layer or buffer that the image should be drawn to. 301 * 302 * @param mimetype 303 * The mimetype of the image data that will be received along this stream. 304 * 305 * @param x 306 * The X coordinate of the upper-left corner of the rectangle within the 307 * destination layer or buffer that the image should be drawn to. 308 * 309 * @param y 310 * The Y coordinate of the upper-left corner of the rectangle within the 311 * destination layer or buffer that the image should be drawn to. 312 * 313 * @return 314 * Zero if the image stream was successfully created, non-zero otherwise. 315 */ 316int guacenc_display_create_image_stream(guacenc_display* display, int index, 317 int mask, int layer_index, const char* mimetype, int x, int y); 318 319/** 320 * Returns the stream having the given index. If no such stream exists, NULL 321 * will be returned. 322 * 323 * @param display 324 * The Guacamole video encoder display to retrieve the image stream from. 325 * 326 * @param index 327 * The index of the stream to retrieve. All valid stream indices are 328 * non-negative. 329 * 330 * @return 331 * The stream having the given index, or NULL if the index is invalid or 332 * a no such stream exists. 333 */ 334guacenc_image_stream* guacenc_display_get_image_stream( 335 guacenc_display* display, int index); 336 337/** 338 * Frees all resources associated with the stream having the given index. If 339 * the stream has not been allocated, this function has no effect. 340 * 341 * @param display 342 * The Guacamole video encoder display associated with the image stream 343 * being freed. 344 * 345 * @param index 346 * The index of the stream to free. All valid stream indices are 347 * non-negative. 348 * 349 * @return 350 * Zero if the stream was successfully freed or was not allocated, non-zero 351 * if the stream could not be freed as the index was invalid. 352 */ 353int guacenc_display_free_image_stream(guacenc_display* display, int index); 354 355/** 356 * Translates the given Guacamole protocol compositing mode (channel mask) to 357 * the corresponding Cairo composition operator. If no such operator exists, 358 * CAIRO_OPERATOR_OVER will be returned by default. 359 * 360 * @param mask 361 * The Guacamole protocol compositing mode (channel mask) to translate. 362 * 363 * @return 364 * The cairo_operator_t that corresponds to the given compositing mode 365 * (channel mask). CAIRO_OPERATOR_OVER will be returned by default if no 366 * such operator exists. 367 */ 368cairo_operator_t guacenc_display_cairo_operator(guac_composite_mode mask); 369 370#endif 371