[Bf-committers] Preliminary Design (render api)

[Aaron Moore]

What I'm currently thinking, actually, is that instead of a scene
hierarchy, the scene traversal will happen using various get functions
that return handlers or lists of handlers to datablocks. It seems to
me that this is flexible and suited to the task of exporting. For
example, one could use a single handler for each of objects, polygon
meshes, nurbs, curves, and simply assign new data to the handler in
loops. Also, comparing handlers might be a natural way to determine if
two datablocks are instances of the same one.

At any rate here is my WIP. I have prioritized the most basic
functionality. All the void*s are so that multiple kinds of handlers
can be returned from a single function. Also, it has a bit of a
renderman slant, because that's the system I know the best.

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.


===================

   Render API

===================

---------------
 Callbacks
---------------

These will be placed in the appropriate places within
 render pipeline.

// at beginning of whole render
setup

// for each frame
render_frame

// at end of render
finish

// when the render needs to be canceled for any reason
abort

---------------
 API Functions
---------------



 >>> SETTINGS

typedef enum COORDINATE_SYSTEM{
LOCAL,
GLOBAL,
VIEW,
SCREEN,
RASTER
} COORDINATE_SYSTEM;

// get or set the current coordinate system from which
//  all transformations are measured.
COORDINATE_SYSTEM get_coordinate_system()
void set_coordinate_system( COORDINATE_SYSTEM new )

int get_image_width()
int get_image_height()

 >>> CAMERA

typedef enum CAMERA_TYPE{
PERSPECTIVE,
ORTHAGONAL
}

CAMERA_TYPE get_camera_type()
float get_lens()
float get_clip_start()
float get_clip_end()


 >>> ALL SCENE DATA


// from is a pointer which specifies a
//  structure to perform this operation on. so
//  you don't have to perform the operation on the
//  whole scene hierarchy, you can instead perform
//  it on a small part.
// from could be:
//   - the scene
//   - a group
//   - a list already retrieved
//   - a struct describing a bounding box in space

// returns a list of all data which is instanced multiple times within from
void *get_instanced_data( void *from )

// returns a list of data that uses used data within from.
//  for example, if used was a material, you could return
//  all objects which use that material. This is useful if that
//  material has a lightgroup, for example.
//  If recursive, it travels up to the top of every data-chain,
//  else it only returns data that directly uses used.
void *get_data_using( void *used, void *from, bool recursive )

// for traversing lists, returns false when list ends
//  these allow further hiding of implementation details
bool get_next( void *data )
bool get_prev( void *data )



 >>> OBJECT

// If invert is true, return the reverse transformation.

// returns transformation matrix from local coordinates to
//  whatever coordinates we are currently in
void get_transformation( void *object, transform[][4], bool invert )

// 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 )

// returns the light or geometry data
void *get_data( void *object )



 >>> LIGHTS

// returns a list of all light objects within from
void *get_lights( void *from )


float get_intensity( void *light )
float get_falloff_distance( void *light )



 >>> GEOMETRY

// returns all geometry objects within from
void *get_geometry( void *from )

typedef enum GEOMETRY_TYPE{
POLYGON_MESH,
SUBDIVISION_SURFACE,
NURB_SURFACE,
METABALL,
CURVE,
PARTICAL_SYSTEM
} GEOMETRY_TYPE;

// returns a list of type geometry handlers within from
void *get_geometry_by_type( GEOMETRY_TYPE type, void *from )



 >>> POLYGON MESH
 >>> SUBDIVISION SURFACE

// returns a list of verticies, edges, faces
void *get_verticies( void* geometry )
void *get_edges( void* geometry )
void *get_face( void* geometry )

// returns the coordinates of the vertex
void get_coordinates( void *vertex, float coordinates[3] )
// data is either an edge or a face. indicies of verticies which
define the edge or face.
void *get_indices( void *data )

int get_index( void *index )


 --- Aaron