[Bf-committers] Final Design of Basics (render api)

[Aaron Moore]

Hi Mathias:

> Do i understand correctly that in the end, all "handlers" are
> just void pointers in disguise again? And for each API call i
> have to pass it to tell the API which element i mean?
> Will it always point to the same struct that just gets updated?

Handlers are an abstraction from directly accessing library data. They
store the pointers to the data and meta information about the data,
like if it has changed since the last frame. Yes, they will always
point to the same data that merely got updated.

> It also seems you plan an extra callback for each and every
> property, and only return primitive types (int, float or arrays
> of ints, floats and chars...).
> I think that way  those could become quite a lot of function and
> may grow faster than people can update their plugins...

There is one of two choices here:
   - API functions (not callbacks) that return each property, or
   - Structures that contain that information.
I did think about this decision carefully, even though I didn't write
down the details of that thought process in the wiki, I suppose I will
after finishing this email.

Why No To Structs:
Structures require copying data unnecessarily. Structures also raise
issues with blender deciding the format of things like dynamic arrays.
Renderman and blender internal, at the very least, do not want vertex
arrays formatted the same way, and this decision should be made by the
plugin and not the API, because it varies per renderer. These
structures have the potential to expose implementation details of
blender's internal structures more easily than the functions.

Why Yes To Functions:
First of all, in terms of extensibility, they are functionally
equivalent (pun, ugg...) to structures:
------------------------------
lens = Rapi_get_camera_lens( scene )
vs.
lens = camera_settings->lens
------------------------------
Second, since the interface to these functions (the names, arguments,
return values), won't change after the api is released, there will be
no more catching up to do by plugin writers than in the structures
model, again: functionally equivalent. Though extending structures is
possible I think it lends itself less naturally to the task of
extending than simply adding new functions.

However, copying lists of settings (render settings, camera settings,
light settings, mesh rendering settings) will not create significant
inefficiency any more than the handler system is already doing, so so
we could change this type of model for these sections of the API:

RapiCameraSettings *Rapi_get_camera_settings( scene )
camera.lens
camera.depth_of_field
camera.start_clip

After all, the systems are functionally equivalent. The only
differences are 1) structs require copying, and 2) syntax.

This is a good point. These two systems for the settings should be
discussed and decided on, however, I will NOT include structures that
give direct acces to geometry data (arrays of vertices, edges, faces),
due to the problems with this discussed in "Dynamic Arrays."

> Also some snippets of the pseudo code look a bit odd to me...
> /* Export Geometry */
> for( object = Rapi_get_objects( scene, Rapi_GEOMETRY );
>         Rapi_object_exists( object );
>         Rapi_get_next_object( object ) )
> {
>         geometry = Rapi_object_get_geometry( object );
>         Rapi_geometry_to_polygon_mesh( geometry );
>         export_polygons( object );
> }
>
> Why does export_polygons() get "object" and not "geometry"?
> And when is the geometry Rapi_geometry_to_polygon_mesh()
> potentially creates freed again?

Yes, I should switch around the way this works, I didn't think about
the pseudocode implementation carefully enough: the function should be
called "export_geometry" take the object as an argument (because it
needs the transformation info), and do the conversion in the function.

Freeing meta-data structures is a subject I need to write out in the
render API page. I have worked on it in my head, but not written it
down yet. I'm considering 2 systems:
  1) the render API automatically detects when meta-data is no longer
in use, and frees them.
  2) a generic free-unused-metadata function allows the user to tell
the API to go through and free all unused data.

A messy alternative to either of these is that api functions for each
handler type exist to free that handler type.

I will work on writing out a firm decision on this in the render API page.

> And what about ID Properties now? Is there a way planned
> to get them? Because i think i *really* need them. All the new
> yafray features are configured there, because blender settings
> simply do no apply for many things.
> Setting those has not to be your problem, we currently use/develop a
> python interface that gives a nice compromise between integration
> and support for non-blenderish things.

Ah, right, no harm in adding functions to retrieve id property
name,value pairs from library data, as this will be needed eventually.
I'll put a draft of this in, thanks for the heads up.

Aaron