Filters are arranged in a three-level hierarchy:

1. Filter libraries, which are a loose collection of filter-sets. These
   allow filters to be grouped together to avoid having hundreds of
   files. It also makes shared access to data easier.
2. Filter-sets, which are tightly coupled groups of filters. Each
   filter-set may have state, may depend upon other filter sets and may
   only be loaded as a unit.
3. Filters, which provide the actual callback functions to run. A filter
   set may require multiple callbacks to be run at different times (e.g.
   before and after invocation). Filters may have ordering dependencies
   on other filters to ensure correct sequencing, but these dependencies
   do not require the other filters to be loaded.

Each library must define the function

void initialise_filter_library(void)

which will register all the filter-sets in the library. It registers a
filter-set by calling

register_filter_set("setname", info);

info is a filter_set_info structure, which contains the following fields:

init: a function that is called when the filter set is loaded
(which occurs in a thread-safe environment). It has the signature
bool initialise_filter_set(filter_set *handle)
and returns true if loading was successful.

done: An optional shutdown function called at program termination. It
has the form
void destroy_filter_set(filter_set *handle)

command_handler: a callback function for config file commands. The
signature is
bool configure_filter_set(filter_set *handle, const void *name, const void *value)
It should return true if the command was processed, false otherwise.
If the name was recognised but the value was illegal, it should print a
warning to stderr, ignoring the command and return true (returning
false would cause a confusing error about the *name* being illegal). The
handler is called before the initialiser, so it can control the
actions of the latter. Any initialisation that needs to happen prior to
the configurator must be done in initialise_filter_library
(and should be minimal, given that the filter-set might never be
loaded).

call_state_space: the number of bytes that should be made available for
each call passed through the library. This can be used to communicate
data between filters. Usually set to 0 i.e. unused.

context_state_space: the number of bytes that should be made available
within each context state structure. This should be used for
per-context state. Usually set to 0 i.e. unused.

A filter-set initialiser must do the following, apart from any internal
initialisation:
- register individual filters:
  filter *filter_handle = register_filter(handle, "filtername", callback)
- list ordering requirements between filters
  register_filter_depends("second", "first") - where either may be in
  another filter-set (even in another library, or even not exist)
- get handles to other filter-sets
  filter_set *other_handle = get_filter_set_handle("other_set_name")
  which will return NULL if the latter was not found (but will return
  a meaningful value even if it won't be used).
- specify dependencies on other filter-sets
  register_filter_set_depends("set1", "set2")
- get symbols from other filter-sets, if necessary:
  foo_ptr = (void (*)(void)) get_filter_set_symbol(other_handle, "foo")
  This will also return a meaningful value even if the other filter
  will never be used, provided the symbol is defined. Passing NULL as
  the first argument will look up symbols in the main library.

Note that there is a fundamental difference between filter dependencies
and filter-set dependencies: the first is an ORDERING relationship, and
limits the order in the filters can run if both are loaded, while
the latter is an ENABLING relationship, and determines which extra
filter-sets must be loaded in order to guarantee correct operation.
The filter dependencies are only implicitly transitive: if A must come
before B and B before C, it is still possible for A to come after C if
B is never loaded.

The callback function for a filter looks like this:

bool filter_callback(function_call *call, const callback_data *data)

and should return false to halt processing of this call. The
callback_data structure contains two pointers, call_data and
context_data. These are respectively the per-call and per-context data
requested during initialisation. The data is initially set to all
zeros. It is also possible to obtain pointers to the per-call state of
other filter sets (which is the intention of this extension) by calling

get_filter_set_call_state(call, other_handle)

and to the per-context state by calling

get_filter_set_context_state(context, other_handle).


Some guidelines
---------------
- Be sure to specify an ordering dependency between any filter and the
"invoke" filter, unless you truly do not care.
- Try not to halt calls. Rather let them run and then overwrite the
return value and possibly the GL state that it set. Otherwise the call
will not appear in the log.


Conventions
-----------

- If your filter runs after invoke and makes GL calls, then the
initialisation should call register_filter_set_renders on the set and
register_filter_post_renders on the filter (from glutils.h). Protect
any rendering like this:

if (begin_internal_render())
{
    CALL_glFrob();
    CALL_glBaz();
    end_internal_render("filtername", true);
}

Replace true with false if you expect errors and wish to ignore them.

- If you intend to use any logging, see the comments at the top of
src/log.h for instructions.
