Func Explosion...

[Shaltif]

[SILL]
Well, first day of March!  I was never good with due dates ;P.  As noted, I originally planned to have almost all my documentation done by now...unfortunately, I got side tracked and instead of writing documentation, I made more functions to document!

Now that everything is in, here is a more complete list of what I have added:

sill_resource_list(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_UINT offset, SILL_UINT type);

sill_instance_proximity(SILL_RESOURCE *result, SILL_REAL x, SILL_REAL y, SILL_UINT pos, SILL_UINT order);
sill_instance_proximity_alt(SILL_RESOURCE *result, SILL_REAL x, SILL_REAL y, SILL_UINT pos, SILL_UINT order, SILL_RESOURCE object);
sill_instance_proximity_list(SILL_RESOURCE *result, SILL_REAL x, SILL_REAL y, SILL_UINT pos, SILL_UINT order, SILL_RESOURCE *list, SILL_UINT size);

sill_instance_list_creation(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_UINT offset, SILL_UINT age);
sill_instance_list_object(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_UINT offset, SILL_RESOURCE object);
sill_instance_list_depth(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_UINT offset, SILL_UINT ascending);
sill_instance_list_proximity(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_UINT offset, SILL_REAL x, SILL_REAL y, SILL_UINT furthest);
sill_instance_list_region(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_REAL x, SILL_REAL y, SILL_REAL width, SILL_REAL height);

sill_instance_list_sort_creation(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_UINT order);
sill_instance_list_sort_depth(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_UINT order);
sill_instance_list_sort_proximity(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_REAL x, SILL_REAL y, SILL_UINT order);

sill_instance_list_filter_creation(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_UINT min, SILL_UINT max);
sill_instance_list_filter_object(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_RESOURCE object);
sill_instance_list_filter_depth(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_INT min_depth, SILL_INT max_depth);
sill_instance_list_filter_proximity(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_REAL x, SILL_REAL y, SILL_REAL min_radius, SILL_REAL max_radius);
sill_instance_list_filter_region(SILL_RESOURCE *list, SILL_UINT *size, SILL_UINT max_size, SILL_REAL x, SILL_REAL y, SILL_REAL width, SILL_REAL height);

As you can see, a simple 'instance nearest' suggestion became an entirely new API based on the idea of manipulating instances on lists.  This API does give some nice easy tools, especially the filtering options (for example, you can use filter_proximity to filter a list of instances to just those in a ring around a specified point).

sill_resource_list_size() has been retired.  Instead, I opted for the option of passing NULL for the *list parameter in most of these functions (so if you just want the size, you can obtain just that using the same function).  Otherwise, almost all of these functions would have required a separate sill_instance_list_..._size() type function, which is just plain overkill.

I'm still debating in my head whether to keep the max_size parameter, or to condense *size and max_size into one (thus users would pass the address to a variable that stores the max possible size for the array, with the variable changing to the actual number of entries on the list).  On one hand it's less variables for me to deal with and less parameter to remember...on the other, it can be a bit confusing since no other function in Sill would operate in this fashion (another one of those 'exception' setups).  Of course, no other function in Sill alters a list given to it directly (notice how in the sort and filter functions, you pass a list which is directly manipulated, thus a user doesn't need to specify a destination list).

Once I'm confident with my final setup for these functions, I'll document them down.

~Brandon