From BlenderWiki

Jump to: navigation, search


This is the page for the Render API implementation design. This page is for developers of the API. User documentation is here: Render API.

[edit] General

In general the render api requires three kinds of operations, increasing in difficulty:

  1. Retrieving - data merely has to be found and returned. Example: light intensity.
  2. Processing - data must be found and used in calculations and then returned. Example: translation vector.
  3. Deriving - data does not exist and must be derived. Example: final mesh used in rendering.

Note: all animated objects have 'derived' status, because of the update needed for the new frame.

[edit] Common Members

  • source - a pointer to the library data within blender.

[edit] Objects

Requirements. Objects need to be retrieved by type and by instancing status. They may have Object structures within the blender database or be procedural objects generated by duplicators. Objects must be able to report their name and transformation. Because of animation, generated data must be able to be re-generated (the method of generation must be accessible again). Because of the requirement for objects to be able to appear and disappear, the order of objects returned by queries will not be retained, instead, either object names or temporary custom data will be used to identify a new version of the same object (for motion blur).

Filtering. Where some objects in the render API don't have corresponding Object structs, others that have object structs will be filtered out. These include objects which by nature cannot be rendered, and objects which are flagged for non-render. Objects may be flagged for non-render in the outliner or using layers, of these methods, layers can be animated.

Animation. Objects may pop in from a hidden layer or spawned by a particle system duplicator. Also, due to the requirement to be able to animate, generated data must include information on how it was generated so that it may be updated on the new frame. This concerns duplicate objects, and collapsed transformation information.

[edit] Objects Design

Structures.

  • Scene - lists of holders and indexes for performing queries.
  • Object - an index of the selected objects, and a current pointer.
  • ObjectHolder - source Object structure, and collapsed data.
  • ObjectPointer - pointers to object holders.

3 Layers.

  • Index - a list of object pointers, allows organization by various methods.
  • Holders - a list of objects holders. Only one object holder exists in the API backend for each object.
  • Blender Database - Object structures referenced by object holders.

Image:three_object_layers.png

Scene Members:
Holders.

  • objects - all objects which will participate in the current render job.

Indexes.

  • pointlights, meshes, curves, etc. - indexed by type.
  • originals - index the first instance of each object with multiple instances.

Image:instances2.png

It may be necessary to eventually add pointers from object holders back to the object pointers that index them for a particular index. If an operation on one index affected the status of another index, this would allow a function to update both easily. Here is a hypothetical diagram of what this might look like:

Image:RenderAPI_double_index_pointers.png

[edit] Index Instance Function

Here is a diagram of the design of the index_instance function. The diagram is a little complecated, so let me explain a few things. First, there are 3 lists involved:

  1. polygon_mesh - a list (index) of pointers to the polygon mesh types within the holders list. This would be passed to the function as the "source" parameter.
  2. objects - the holders list, not touched in the function execution but important because it is the list being indexed.
  3. originals - a list (index) of pointers to the first instance found of each set of instances.

There are also 3 variables used:

  1. candidate - the first pointer found in polygon_mesh (source) which is not part of an instance set.
  2. original - a copy of the candidate placed on the originals (destination) list, and thereafter used for comparison.
  3. current - the current pointer in polygon_mesh (source) not marked as an instance.

The function works by marching forward through polygon_mesh (source) comparing each candidate to all the currents which follow it. If the candidate and the current have the same data (light, mesh, etc.) then they are instances (this situation is illustrated with the purple oval). When the first occurrence of multiple instances is found, the pointer to candidate is copied to originals.

Whenever multiple instances are found they are marked as instances by a pointer to the "original," the first instance found. This original is pointed to on the originals list, and generally used for storing data which all instances will need, such as the TemporaryData structure.

At the end of this function the memory will look like the diagram at the bottom of the Scene Members section above.

Image:renderAPI_index_instance3.png

Retrieved from "http://wiki.blender.org/index.php/Dev:Ref/Design_docs/Render_API/Implementation"