From c3584c8d0413894c34acbadc74a859bb71650b8e Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Thu, 3 Mar 2016 12:27:59 -0800 Subject: [PATCH] GUAC-1389: Document graphical functions and handlers. --- src/protocols/vnc/cursor.c | 7 ++-- src/protocols/vnc/cursor.h | 31 ++++++++++++++- src/protocols/vnc/display.c | 7 ++-- src/protocols/vnc/display.h | 77 ++++++++++++++++++++++++++++++++++--- 4 files changed, 108 insertions(+), 14 deletions(-) diff --git a/src/protocols/vnc/cursor.c b/src/protocols/vnc/cursor.c index b7a92082..c25a489f 100644 --- a/src/protocols/vnc/cursor.c +++ b/src/protocols/vnc/cursor.c @@ -43,6 +43,7 @@ #include #include +#include #include #include @@ -85,15 +86,15 @@ void guac_vnc_cursor(rfbClient* client, int x, int y, int w, int h, int bpp) { /* Read current pixel value */ switch (bpp) { case 4: - v = *((unsigned int*) fb_current); + v = *((uint32_t*) fb_current); break; case 2: - v = *((unsigned short*) fb_current); + v = *((uint16_t*) fb_current); break; default: - v = *((unsigned char*) fb_current); + v = *((uint8_t*) fb_current); } /* Translate mask to alpha */ diff --git a/src/protocols/vnc/cursor.h b/src/protocols/vnc/cursor.h index 7eb8f5e1..6d80ec18 100644 --- a/src/protocols/vnc/cursor.h +++ b/src/protocols/vnc/cursor.h @@ -20,14 +20,41 @@ * THE SOFTWARE. */ -#ifndef GUAC_DISPLAY_CURSOR_H -#define GUAC_DISPLAY_CURSOR_H +#ifndef GUAC_VNC_CURSOR_H +#define GUAC_VNC_CURSOR_H #include "config.h" #include #include +/** + * Callback invoked by libVNCServer when it receives a new cursor image from + * the VNC server. The cursor image itself will be split across + * client->rcSource and client->rcMask, where rcSource is an image buffer of + * the format natively used by the current VNC connection, and rcMask is an + * array if bitmasks. Each bit within rcMask corresponds to a pixel within + * rcSource, where a 0 denotes full transparency and a 1 denotes full opacity. + * + * @param client + * The VNC client associated with the VNC session in which the new cursor + * image was received. + * + * @param x + * The X coordinate of the new cursor image's hotspot, in pixels. + * + * @param y + * The Y coordinate of the new cursor image's hotspot, in pixels. + * + * @param w + * The width of the cursor image, in pixels. + * + * @param h + * The height of the cursor image, in pixels. + * + * @param bpp + * The number of bytes in each pixel, which must be either 4, 2, or 1. + */ void guac_vnc_cursor(rfbClient* client, int x, int y, int w, int h, int bpp); #endif diff --git a/src/protocols/vnc/display.c b/src/protocols/vnc/display.c index fbc740a4..340b27ca 100644 --- a/src/protocols/vnc/display.c +++ b/src/protocols/vnc/display.c @@ -42,6 +42,7 @@ #include #include +#include #include #include @@ -99,15 +100,15 @@ void guac_vnc_update(rfbClient* client, int x, int y, int w, int h) { switch (bpp) { case 4: - v = *((unsigned int*) fb_current); + v = *((uint32_t*) fb_current); break; case 2: - v = *((unsigned short*) fb_current); + v = *((uint16_t*) fb_current); break; default: - v = *((unsigned char*) fb_current); + v = *((uint8_t*) fb_current); } /* Translate value to RGB */ diff --git a/src/protocols/vnc/display.h b/src/protocols/vnc/display.h index e9eaf77b..cd02e269 100644 --- a/src/protocols/vnc/display.h +++ b/src/protocols/vnc/display.h @@ -29,23 +29,88 @@ #include /** - * Called for normal binary VNC image data. + * Callback invoked by libVNCServer when it receives a new binary image data. + * the VNC server. The image itself will be stored in the designated sub- + * rectangle of client->framebuffer. + * + * @param client + * The VNC client associated with the VNC session in which the new image + * was received. + * + * @param x + * The X coordinate of the upper-left corner of the destination rectangle + * in which the image should be drawn, in pixels. + * + * @param y + * The Y coordinate of the upper-left corner of the destination rectangle + * in which the image should be drawn, in pixels. + * + * @param w + * The width of the image, in pixels. + * + * @param h + * The height of the image, in pixels. */ void guac_vnc_update(rfbClient* client, int x, int y, int w, int h); /** - * Called for updates which contain data from existing rectangles of the - * display. + * Callback invoked by libVNCServer when it receives a CopyRect message. + * CopyRect specified a rectangle of source data within the display and a + * set of X/Y coordinates to which that rectangle should be copied. + * + * @param client + * The VNC client associated with the VNC session in which the CopyRect + * was received. + * + * @param src_x + * The X coordinate of the upper-left corner of the source rectangle + * from which the image data should be copied, in pixels. + * + * @param src_y + * The Y coordinate of the upper-left corner of the source rectangle + * from which the image data should be copied, in pixels. + * + * @param w + * The width of the source and destination rectangles, in pixels. + * + * @param h + * The height of the source and destination rectangles, in pixels. + * + * @param dest_x + * The X coordinate of the upper-left corner of the destination rectangle + * in which the copied image data should be drawn, in pixels. + * + * @param dest_y + * The Y coordinate of the upper-left corner of the destination rectangle + * in which the copied image data should be drawn, in pixels. */ -void guac_vnc_copyrect(rfbClient* client, int src_x, int src_y, int w, int h, int dest_x, int dest_y); +void guac_vnc_copyrect(rfbClient* client, int src_x, int src_y, int w, int h, + int dest_x, int dest_y); /** - * Called when the pixel format of future updates is changing. + * Callback invoked by libVNCServer when the pixel format of future graphical + * updates is changing. + * + * @param client + * The VNC client associated with the VNC session whose pixel format is + * changing. + * + * @param color_depth + * The new color depth, in bits per pixel. Valid values are 8, 16, 24, and + * 32. */ void guac_vnc_set_pixel_format(rfbClient* client, int color_depth); /** - * Called when the display is being resized (or initially allocated). + * Overridden implementation of the rfb_MallocFrameBuffer function invoked by + * libVNCServer when the display is being resized (or initially allocated). + * + * @param client + * The VNC client associated with the VNC session whose display needs to be + * allocated or reallocated. + * + * @return + * The original value returned by rfb_MallocFrameBuffer(). */ rfbBool guac_vnc_malloc_framebuffer(rfbClient* rfb_client);