libstage: s/match/lookup/g

Rather than having a per-node match function to facilitate stage
lookups by opaque keys returning a boolean result, make it a
more general lookup returning a stage_t *.

It's still basically a boolean, where NULL is a miss.  But by
returning the stage_t *, it enables things like encapsulated
stages for caching purposes where a node might represent an
isolated stage it can propagate lookups down to and return
the results out of.

When the match function only returned a 1/0, and the outer
lookup machinery returned the current stage node on a hit,
there was no way to hand out arbitrary stage pointers.

2 files changed, 24 insertions, 20 deletions

diff --git a/src/stage.c b/src/stage.c
index 44a0378..e596ab0 100644
--- a/src/stage.c
+++ b/src/stage.c
@@ -34,13 +34,13 @@ struct stage_t {
 
 	stage_render_func_t	*render;	/* render object */
 	stage_free_func_t	*free;		/* free object */
-	stage_match_func_t	*match;		/* match object against key */
+	stage_lookup_func_t	*lookup;	/* lookup object against key */
 	void			*object;	/* object */
 };
 
 
 /* minimally initialize a stage to carry an object */
-static void _stage_set_object(stage_t *stage, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_match_func_t *match_func)
+static void _stage_set_object(stage_t *stage, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_lookup_func_t *lookup_func)
 {
 	assert(stage);
 	assert(name);
@@ -48,13 +48,13 @@ static void _stage_set_object(stage_t *stage, const char *name, void *object, st
 	strncpy(stage->name, name, sizeof(stage->name));
 	stage->render = render_func;
 	stage->free = free_func;
-	stage->match = match_func;
+	stage->lookup = lookup_func;
 	stage->object = object;
 }
 
 
 /* allocate a stage, this purely creates a stage in isolation and assigns its associated name, object and functions */
-static stage_t * _stage_new(const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_match_func_t *match_func)
+static stage_t * _stage_new(const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_lookup_func_t *lookup_func)
 {
 	stage_t	*stage;
 
@@ -66,7 +66,7 @@ static stage_t * _stage_new(const char *name, void *object, stage_render_func_t
 	for (int i = 0; i < STAGE_LAYERS_MAX; i++)
 		dll_init(&stage->layers[i]);
 
-	_stage_set_object(stage, name, object, render_func, free_func, match_func);
+	_stage_set_object(stage, name, object, render_func, free_func, lookup_func);
 
 	return stage;
 }
@@ -86,14 +86,14 @@ static void _stage_free(stage_t *stage)
 
 /* returns a new stage, attached at the specified layer under parent if supplied */
 /* layer has no effect when parent == NULL */
-stage_t * stage_new(stage_t *parent, int layer, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_match_func_t *match_func)
+stage_t * stage_new(stage_t *parent, int layer, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_lookup_func_t *lookup_func)
 {
 	stage_t	*stage;
 
 	assert(parent || !layer);
 	assert(layer < STAGE_LAYERS_MAX);
 
-	stage = _stage_new(name, object, render_func, free_func, match_func);
+	stage = _stage_new(name, object, render_func, free_func, lookup_func);
 	if (!stage)
 		return NULL;
 
@@ -107,14 +107,14 @@ stage_t * stage_new(stage_t *parent, int layer, const char *name, void *object,
 
 
 /* replaces a given stage's object-related properties but otherwise keeping the existing state */
-void stage_replace(stage_t *stage, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_match_func_t *match_func)
+void stage_replace(stage_t *stage, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_lookup_func_t *lookup_func)
 {
 	assert(stage);
 
 	if (stage->free)
 		stage->free(stage, stage->object);
 
-	_stage_set_object(stage, name, object, render_func, free_func, match_func);
+	_stage_set_object(stage, name, object, render_func, free_func, lookup_func);
 }
 
 
@@ -288,7 +288,7 @@ void stage_render(const stage_t *stage, void *render_ctxt)
 }
 
 
-/* lookup a stage from a name, returns first match */
+/* lookup a stage from a name, returns first hit */
 stage_t * stage_lookup_name(stage_t *stage, const char *name)
 {
 	assert(stage);
@@ -312,8 +312,8 @@ stage_t * stage_lookup_name(stage_t *stage, const char *name)
 }
 
 
-/* lookup a stage by an opaque key using the per-stage match_func when present,
- * returns first match, does not support multiple matches.
+/* lookup a stage by an opaque key using the per-stage lookup_func when present,
+ * returns first hit, does not support multiple hits.
  * Intended for rudimentary non-overlapping spatial searches like picking of
  * basic 2D UI elements.
  */
@@ -321,17 +321,21 @@ stage_t * stage_lookup_key(stage_t *stage, void *key)
 {
 	assert(stage);
 
-	if (stage->match && stage->match(stage, stage->object, key))
-		return stage;
+	if (stage->lookup) {
+		stage_t	*hit = stage->lookup(stage, stage->object, key);
+
+		if (hit)
+			return hit;
+	}
 
 	for (int i = 0; i < STAGE_LAYERS_MAX; i++) {
 		stage_t	*s;
 
 		DLL_FOR_EACH_ENTRY(&stage->layers[i], s, stage_t, layer) {
-			stage_t	*match = stage_lookup_key(s, key);
+			stage_t	*hit = stage_lookup_key(s, key);
 
-			if (match)
-				return match;
+			if (hit)
+				return hit;
 		}
 	}
 
diff --git a/src/stage.h b/src/stage.h
index 5416af6..c5d0173 100644
--- a/src/stage.h
+++ b/src/stage.h
@@ -24,10 +24,10 @@ typedef struct stage_t stage_t;
 
 typedef void (stage_render_func_t)(const stage_t *stage, void *object, float alpha, void *render_ctxt);
 typedef void (stage_free_func_t)(const stage_t *stage, void *object);
-typedef int (stage_match_func_t)(const stage_t *stage, void *object, void *key);
+typedef stage_t * (stage_lookup_func_t)(const stage_t *stage, void *object, void *key);
 
-stage_t * stage_new(stage_t *parent, int layer, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_match_func_t *match_func);
-void stage_replace(stage_t *stage, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_match_func_t *match_func);
+stage_t * stage_new(stage_t *parent, int layer, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_lookup_func_t *lookup_func);
+void stage_replace(stage_t *stage, const char *name, void *object, stage_render_func_t *render_func, stage_free_func_t *free_func, stage_lookup_func_t *lookup_func);
 stage_t * stage_free(stage_t *stage);
 void stage_render(const stage_t *stage, void *render_ctxt);
 void stage_clear(stage_t *stage);