GUAC-1389: Document graphical functions and handlers.

src/protocols/vnc/cursor.c

@@ -43,6 +43,7 @@
 
 #include <stdarg.h>
 #include <stdio.h>
+#include <stdint.h>
 #include <stdlib.h>
 #include <syslog.h>
 
@@ -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 */

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 <rfb/rfbclient.h>
 #include <rfb/rfbproto.h>
 
+/**
+ * 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

src/protocols/vnc/display.c

@@ -42,6 +42,7 @@
 
 #include <stdarg.h>
 #include <stdio.h>
+#include <stdint.h>
 #include <stdlib.h>
 #include <syslog.h>
 
@@ -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 */

src/protocols/vnc/display.h

@@ -29,23 +29,88 @@
 #include <rfb/rfbproto.h>
 
 /**
- * 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);