$Id: api-proposal.html,v 1.1 2001/05/07 10:16:32 strubi Exp $

Development of the Python API and the Python Toolbox

Technical overview -- responsible: strubi@blender.nl

TOC:

  1. Motivation for future API/Toolbox
  2. Analysis of the current status
  3. API roadmap
  4. Supporting scripts/PyToolbox
  5. Development
  6. Quality approvement
  7. Revenues

Functionality of the Python API

The Python API allows a power user to access the Blender data structures and helps a developer to rapidly prototype and integrate a feature into the program environment in a modularized way. This implies dynamical import of modules at runtime: a plugin system.

Strengths of Python:

Motivation for future API/Toolbox

Analysis of the current status

API versions versus API versions

History:
  1. First low level Creator API was written by Daniel Dunbar around 1999-2000
  2. This API was replaced later by Jan Walter around August 2000 through an API with different way of access. This API could neither be finished nor stabilized due to the known organizational problems.
  3. At the same time, a separate API for the GameEngine has been written by Erwin Coumans, using a syntax non consistent with both of the other APIs and lacking error handling.
These 3 APIs, especially when the first API was removed for a certain time, caused and still cause a lot of confusion among the community. A little number of applications have been developed in the first Creator API only.
Therefore, the decision is made, to support and extend the first API and later on merge it with the GameEngine API.
 

Comparison/characteristics of the APIs

  
API 1 (Daniel Dunbar) API 2 (Jan Walter) API 3 (Erwin Coumans)
(+) OO like access to Blender datastructures (Meshes, etc.) (-) Unflexible, direct access to the Blender data (low level structure is visible to the user) (-) different way of data access (different syntax), not consistent with API1 and API2
(-) Little representation of the Blender Scenegraph (+) More representation of the Blender Scenegraph (o) no scenegraph representation
(+) mesh data access stable mesh data access unstable and broken (-) different syntax
(o) Wrapper objects are copies of or descriptor objects for the internal data. There is no synchronization happening between Blender objects and Python Objects (o) Wrapper objects are copies of or descriptor objects for the internal data (o) Wrapper objects are true C Objects. This is efficient in some way, but introduces nasty problems with synchronization (reference counting between Python and C objects), due to the design.
(+) lots of functionality, future compatible from the users (python programmers) perspective (-) future incompatible (-) little functionality, missing error handling

Proposal for this problem's solution

Long term: Solve these deficiencies by gradually merging the benefits of all APIs into one API. This will most likely be the part of the Blender 3.0 reconstruction process. A lot of research and prototyping will have to be done in order to determine a stable design.
Short term: the most important issue is the future compatibility and stability from the Python user's perspective, i.e. the API syntax should not change again. Also, a lot of discussion should be done about a logical design.
 

API roadmap

A high level API usable by a non-experienced Blender User should meet the following conditions: Extending the current C-API code is time consuming and error prone on a higher level of complexity. Also, it is hard to maintain and problems will be run into as soon as extended features are expected (as pickling of Blender objects, class emulation, etc.)

The options to improve this situation:
 
Option Results
Redesign and rewrite the API using existing C++ classes/ Python extensions (BOOST library, CXX extensions), using the underlying data structure (+) stable API, reusable code, (-) major increase of the binary size, (+) derivable and pickle'able structures (class emulation)
Use current C-API code for low level access, create shadow modules/classes which live on to of the low level modules. See figure below. (+)stable API, (-) code not really reusable for future structure changes, (+) remaining compactness of the code, (+) derivable and pickle'able structures (restricted to python classes), (-) slow and possibly memory consuming

The second option is considered to be rather feasible at the moment. The high level Python API module functionality may gradually transferred into the C-API module if desired (for reasons of speed or little memory consumption)

Illustration of this approach:

Possibly wanted applications(plugins)

The following framework needs to be accomplished to realize the above:
  1. Enable full low level Blender data access
  2. Provide generic scenegraph management module for Import/Export (reuse VRML scenegraph modules?)
  3. Merge existing plugin API with the Python module API
  4. Redesign several internal structures as:

Long term roadmap

Development strategy

The development of a stable set of tools and data access modules will take a lot of time in design.
A proposal was made by the Blender League, to support and manage this development independently from NaN. The way this cooperation and licensing will take place, has still to be decided.
The current overview of the Blender League discussion can be found here: http://www.blender.nl/people/strubi/BL/wishlist.html

Python Toolbox

The Python toolbox will be a set of modules to operate on 3D or image data, independently from the Blender internals. The toolbox routines may be used by Blender itself through a C API or external applications to process data.
For a possible Blender 3.0 redesign, this might be one of the core libraries to process 3D data.

For a summary of the currently wanted features in the toolbox, see http://www.blender.nl/people/strubi/BL/wishlist.html#toolbox

Quality approvement / checklist

See Blender League draft

Revenues

-- Discuss with marketing, community queries --

Several points would need to be thought out to design the Python Extension in order to make profit. A way of making piracy uninteresting should be found.

Support for registered users may include: