From eb450a6b3f375cd2bce733577bdb38599f7bbcb7 Mon Sep 17 00:00:00 2001
From: Michael Jumper <zhangmaike@users.sourceforge.net>
Date: Mon, 20 Aug 2012 19:38:20 -0700
Subject: [PATCH] Prototyped out part of indexed image support, added docs.

---
 libguac/include/hash.h | 96 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/libguac/include/hash.h b/libguac/include/hash.h
index 4a4dc865..c17cc2b8 100644
--- a/libguac/include/hash.h
+++ b/libguac/include/hash.h
@@ -41,6 +41,91 @@
 
 #include <cairo/cairo.h>
 
+/**
+ * A wrapper for a Cairo surface which allows fast image queries (linear time
+ * in the size of the query image). Given an arbitrary input image, the first
+ * occurence of that image within the contained surface can be found quickly.
+ */
+typedef struct guac_indexed_surface {
+
+    /**
+     * The Cairo surface which is indexed.
+     */
+    cairo_surface_t* surface;
+
+} guac_indexed_surface;
+
+typedef struct guac_indexed_surface_subimage {
+
+    /**
+     * The indexed surface this subimage is a part of.
+     */
+    guac_indexed_surface* surface;
+
+    /**
+     * The X coordinate of the upper-left point of the rectangle
+     * of the subimage.
+     */
+    int x;
+
+    /**
+     * The Y coordinate of the upper-left point of the rectangle
+     * of the subimage.
+     */
+    int y;
+
+    /**
+     * The width of the subimage in pixels.
+     */
+    int width;
+
+    /**
+     * The height of the subimage in pixels.
+     */
+    int height;
+
+} guac_indexed_surface_subimage;
+
+/**
+ * Creates a new indexed surface, using the given surface as the image data
+ * source. The given surface will be made searchable such that queries of
+ * images which are at least the given width and height can be resolved
+ * quickly.
+ *
+ * @param surface The Cairo surface to index.
+ * @param min_width The minimum image width to allow for queries.
+ * @param min_height The minimum image height to allow for queries.
+ * @return A newly allocated guac_indexed_surface.
+ */
+guac_indexed_surface* guac_indexed_surface_alloc(cairo_surface_t* surface,
+        int min_width, int min_height);
+
+/**
+ * Frees the given indexed surface.
+ *
+ * @param surface The guac_indexed_surface to free.
+ */
+void guac_indexed_surface_free(guac_indexed_surface* surface);
+
+/**
+ * Given an indexed surface and a query image, finds the rectangle of the
+ * subimage of the indexed surface containing exactly the query image (if
+ * any) and saves the result.
+ *
+ * @param surface The guac_indexed_surface to query.
+ * @param query The image to search for within the indexed surface.
+ * @param result A pointer to an already-allocated
+ *               guac_indexed_surface_subimage which will be modified
+ *               to contain the result if a result is found.
+ * @return Non-zero if the given query image was found within the indexed
+ *         surface, in which case the result will be stored in the given
+ *         guac_indexed_surface_subimage, or zero if the query image could
+ *         not be found, in which case the given guac_indexed_surface_subimage
+ *         will not be modified.
+ */
+int guac_indexed_surface_find(guac_indexed_surface* surface,
+        cairo_surface_t* query, guac_indexed_surface_subimage* result);
+
 /**
  * Produces a 24-bit hash value from all pixels of the given surface. The
  * surface provided must be RGB or ARGB with each pixel stored in 32 bits.
@@ -53,6 +138,17 @@
  */
 unsigned int guac_hash_surface(cairo_surface_t* surface);
 
+/**
+ * Given two Cairo surfaces, returns zero if the data contained within each
+ * is identical, and a positive or negative value if the value of the first
+ * is found to be lexically greater or less than the second respectively.
+ *
+ * @param a The first Cairo surface to compare.
+ * @param b The Cairo surface to compare the first surface against.
+ * @return Zero if the data contained within each is identical, and a positive
+ *         or negative value if the value of the first is found to be lexically
+ *         greater or less than the second respectively.
+ */
 int guac_surface_cmp(cairo_surface_t* a, cairo_surface_t* b);
 
 #endif