GUAC-236: Implement buffer retrieval functions.

src/guacenc/display.c

@@ -94,6 +94,81 @@ int guacenc_display_free_layer(guacenc_display* display,
 
 }
 
+guacenc_buffer* guacenc_display_get_buffer(guacenc_display* display,
+        int index) {
+
+    /* Transform index to buffer space */
+    int internal_index = -index - 1;
+
+    /* Do not lookup / allocate if index is invalid */
+    if (internal_index < 0 || internal_index > GUACENC_DISPLAY_MAX_BUFFERS) {
+        guacenc_log(GUAC_LOG_DEBUG, "Buffer index out of bounds: %i", index);
+        return NULL;
+    }
+
+    /* Lookup buffer, allocating a new buffer if necessary */
+    guacenc_buffer* buffer = display->buffers[internal_index];
+    if (buffer == NULL) {
+
+        /* Attempt to allocate buffer */
+        buffer = guacenc_buffer_alloc();
+        if (buffer == NULL) {
+            guacenc_log(GUAC_LOG_DEBUG, "Buffer allocation failed");
+            return NULL;
+        }
+
+        /* Store buffer within display for future retrieval / management */
+        display->buffers[internal_index] = buffer;
+
+    }
+
+    return buffer;
+
+}
+
+int guacenc_display_free_buffer(guacenc_display* display,
+        int index) {
+
+    /* Transform index to buffer space */
+    int internal_index = -index - 1;
+
+    /* Do not lookup / allocate if index is invalid */
+    if (internal_index < 0 || internal_index > GUACENC_DISPLAY_MAX_BUFFERS) {
+        guacenc_log(GUAC_LOG_DEBUG, "Buffer index out of bounds: %i", index);
+        return 1;
+    }
+
+    /* Free buffer (if allocated) */
+    guacenc_buffer_free(display->buffers[internal_index]);
+
+    /* Mark buffer as freed */
+    display->buffers[internal_index] = NULL;
+
+    return 0;
+
+}
+
+guacenc_buffer* guacenc_display_get_related_buffer(guacenc_display* display,
+        int index) {
+
+    /* Retrieve underlying buffer of layer if a layer is requested */
+    if (index >= 0) {
+
+        /* Retrieve / allocate layer (if possible */
+        guacenc_layer* layer = guacenc_display_get_layer(display, index);
+        if (layer == NULL)
+            return NULL;
+
+        /* Return underlying buffer */
+        return layer->buffer;
+
+    }
+
+    /* Otherwise retrieve buffer directly */
+    return guacenc_display_get_buffer(display, index);
+
+}
+
 guacenc_display* guacenc_display_alloc() {
     return (guacenc_display*) calloc(1, sizeof(guacenc_display));
 }

src/guacenc/display.h

@@ -131,7 +131,8 @@ int guacenc_display_free(guacenc_display* display);
  * returned.
  *
  * @param index
- *     The index of the layer to retrieve.
+ *     The index of the layer to retrieve. All valid layer indices are
+ *     non-negative.
  *
  * @return
  *     The layer having the given index, or NULL if the index is invalid or
@@ -145,7 +146,8 @@ guacenc_layer* guacenc_display_get_layer(guacenc_display* display,
  * the layer has not been allocated, this function has no effect.
  *
  * @param index
- *     The index of the layer to free.
+ *     The index of the layer to free. All valid layer indices are
+ *     non-negative.
  *
  * @return
  *     Zero if the layer was successfully freed or was not allocated, non-zero
@@ -154,5 +156,53 @@ guacenc_layer* guacenc_display_get_layer(guacenc_display* display,
 int guacenc_display_free_layer(guacenc_display* display,
         int index);
 
+/**
+ * Returns the buffer having the given index. A new buffer will be allocated if
+ * necessary. If the buffer having the given index already exists, it will be
+ * returned.
+ *
+ * @param index
+ *     The index of the buffer to retrieve. All valid buffer indices are
+ *     negative.
+ *
+ * @return
+ *     The buffer having the given index, or NULL if the index is invalid or
+ *     a new buffer cannot be allocated.
+ */
+guacenc_buffer* guacenc_display_get_buffer(guacenc_display* display,
+        int index);
+
+/**
+ * Frees all resources associated with the buffer having the given index. If
+ * the buffer has not been allocated, this function has no effect.
+ *
+ * @param index
+ *     The index of the buffer to free. All valid buffer indices are negative.
+ *
+ * @return
+ *     Zero if the buffer was successfully freed or was not allocated, non-zero
+ *     if the buffer could not be freed as the index was invalid.
+ */
+int guacenc_display_free_buffer(guacenc_display* display,
+        int index);
+
+/**
+ * Returns the buffer associated with the layer or buffer having the given
+ * index. A new buffer or layer will be allocated if necessary. If the given
+ * index refers to a layer (is non-negative), the buffer underlying that layer
+ * will be returned. If the given index refers to a buffer (is negative), that
+ * buffer will be returned directly.
+ *
+ * @param index
+ *     The index of the buffer or layer whose associated buffer should be
+ *     retrieved.
+ *
+ * @return
+ *     The buffer associated with the buffer or layer having the given index,
+ *     or NULL if the index is invalid.
+ */
+guacenc_buffer* guacenc_display_get_related_buffer(guacenc_display* display,
+        int index);
+
 #endif