[Bf-committers] Preliminary Design (render api)

[Aaron Moore]

> One thing to be aware of; Objects are not a linear list in a Scene, but
> instead more like a tree (an object can be a vertex-duplicator of
> groups which has objects etc).
> Such instancing (duplicators, groups) happen with single commands in
> Blender now. You cannot get-next or get-prev this.

I do not see why, on principle, the scene must be accessed in a
hierarchical fashion _for rendering_. For the renderer, two types of
data exist: instanced and non-instanced. All duplicators and groups
can be simplified down to collections of object instances which can be
traversed in list fashion. The multiple transformations which go from
world>group>object or from world>duplicator>instance can be collapsed
producing a single, simple interface for working with all of these
structures. This is how I see it.

What do you mean they happen with "single commands." Why would this
affect my above analysis?

> I would look starting with a call that makes a list of all
> render-objects (instanciation, groups, duplicators). This is
> blender-specific, and exporters then don't have to worry about our
> weird features. Instancing information you can store at this stage too.
> (Note; this only for objects, not render geometry)

On principle the API shouldn't make the user do things that it can do.
*How* an object is instanced is not necessary information for a
renderer. I suggest abstracting this away.

> > Also, keep in mind that I've written this from an exporter's point of
> > view. The interface needs to be independent of the implementation.
>
> Maybe, but the exporter is firstmost a Blender exporter, and this same
> API should be used for the internal render too!

The API's job is to give _any_ renderer the information it needs from
the blender database. Making internal-renderer-specific functions in
the API undermines the whole idea, which is to provide the same access
to everyone.

> > // returns transformations from local coordinates to
> > //  whatever coordinates we are currently in
> > void get_location( void *object, location[3], bool invert )
> > void get_rotation( void *object, rotation[3], bool invert )
> > void get_size( void *object, size[3], bool invert )
>
> Why you think this works? Blender won't work this way.
> You need to work exclusively with 4x4 matrix transforms.

I have spent some time looking at DNA_object_types.h, here is a
selection from the Object type definition:

/* rot en drot have to be together! (transform('r' en 's')) */
float loc[3], dloc[3], orig[3];
float size[3], dsize[3];
float rot[3], drot[3];
float quat[4], dquat[4];
float obmat[4][4];
float parentinv[4][4];
float imat[4][4];	/* for during render, old game engine, temporally:
ipokeys of transform  */

Reading this, what I have determined is, that loc[3], rot[3], size[3]
and quat[4] are the location, rotation, size, and quaternion
transformations from world coordinates to this objects local
coordinates, and that these are maintained in parallel with
obmat[4][4] which is the transformation matrix from world coordinates
to object local coordinates. This is the simplest explanation I can
come up. For lack of documentation I made this assumption, however
given than you've told me that it doesn't work this way, I will have
to revisit this and figure out what these _do_ mean.

> > // returns a list of verticies, edges, faces
> > void *get_verticies( void* geometry )
> > void *get_edges( void* geometry )
> > void *get_face( void* geometry )
>
> This is also a bit strange un-blenderish...
> Check how the code works. It might be much more efficient to follow
> conventions for how we've designed derivedmesh for example.

I was familiar with the DerivedMesh interface before I wrote this
design. The idea here is to put a layer of abstraction between the
render API and the blender structures. Here is a diagram of a possible
implementation of a vertex handler, though I would like to complete
and finalize the core functionality of the interface before working on
implementation too heavily:

http://wiki.blender.org/uploads/b/ba/Verticies.png

Hiding the way blender organizes it's structures away allows that
organization to change in the future without changing the interface of
the render API: seperation of implementation and interface.
Furthermore, allowing all data to be browsed in the same way makes the
API easier to learn and use.

Aaron