Dev:Source/Render/API

This page is a proposal and set of ideas for an external render API, using XML, python and C in tandem. Implementing it would obvously be a major task, yet ultimately a worthwhile one.

This proposal is not in any way complete (as it's lack of content should make obvious :) ).

Introduction

Any render api must have three parts:

• A facility to save custom data in materials objects and meshes.
• A flexible way to handle the UI for defining that data, of which python may be the best choice.
• A C api for getting any custom data, processing the render scene, and outputting to the target renderer.

It is my belief that XML would be the best choice for saving custom data. I also think that Python would be the ideal to handle defining UIs. Obviously this would have to interface with the custom blob data project somehow.

The Structure of the API

The render API's entry point would be a python script that would register UI and rendering functions with Blender. The script might look like this:

#RENDER.INTERFACE
from Blender import Render, BPyDataBlob, RenderUI
Render.Register("Aqsis", "C-shared", "Aqsis.DLL", "entry_aqsis")

def draw_scene_ui(self, xmlobj):
  panel code of some sort, using a python-implemented module
  for acessing the xml data.
  BPyDataBlob.DrawPanel(xmlobj)

def event_scene_ui(self, xmlobj, evt, val):
  BPyDataBlob.EventInPanel(xmlobj)

#I don't know schema, so here's a simple idea for making duplicates of preset
#xml trees
xmldef = "<SceneData><GlobalIllum mode="int" samples="int" enabled="int:tog"/></SceneData>"
Render.RegisterPanel("Scene.Aqsis", xmldef, draw_scene_ui, event_scene_ui)

Why XML

For some people, XML can be difficult to use. It doesn't diff as well as fixed-formatted formats, as the human-readable requirements tends to cause differing parsers to lay waste to the whitespace (this is, by the way, all second-hand reports I've gotten).

However, there are advantages to using XML. From a programming point of view, using a tree structure such as XML works very well (and there's no need to use something as complicated as DOM). The fact that it's human-readable also helps to speed up the development process, as it's easy to find problems in the output (and you can always switch to a more fixed binary format later on if you wish). I believe that XML would work well to help prevent a badly-written render wrapper from accumulating data in a .blend. Authors can use a simple python script (written as part of the python side of the API) to monitor all attached XML data, and spot any leaks or errors.

How the Renderer Interface is Communicated With

All data sent to the renderer will be sent in a tree format similar to XML, yet fully binary and very compact (perhaps a special version of sdna). The data will be sent according to a specific protocal, which can perhaps be transformed to maintain compatibility with older render extensions.

The actual implementation of the renderer can be written as a C shared library or a python script. Regardless, the protocal for transferring data would be the same.