Table of Contents
|HappyDoc Generated Documentation|
Python Blender module documentation // Wed Feb 6 14:23:27 CET 2002
This documentation is under development. Some things may not look good, please feedback at the documenation forum at www.blender.org
Copyright (c) 2002 Stichting Blender Foundation. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".GNU Free Documentation License
This is the Developer Documentation for the Blender Python API. It is intented to be a reference only and meant for the experienced programmer and Blender user. It shall be a starting point for better organized documentation writers, and it will be up to them to create a nicer documentation with examples, etc. designed for the starter :-)
The Blender module is split up in several sub modules allowing to import only needed functionality.
import Blender ob = Blender.Object.get('Plane') # get Object with name 'Plane'
from Blender import Object ob = Object.get('Plane')
Creation and deletion of Blender Objects
This paragraph is rather technical, Python script writers can safely skip it, unless they're interested :-)
In Python, the common method is to create a
In Blender, it is often desired to explicitely delete an object (which can still be referenced by another user). Reference counting is only wanted on objects which are not directly owned by a container, such as Mesh objects (which can have several users), or in cases, where the user wants to keep an object around (persistent data) outside of Blender. Keeping references around can easily introduce hardly visible memory shortages though, and requires the user to make sure that the complete namespace is released after the script ends.
To represent clear ownership of objects, there are 3 methods:
Due to Blender 2.x's architecture, it is currently not possible to thoroughly implement these methods (without having to change the low level structures). For the moment, methods 2 and 3 will be chosen where appropriate. For fast access, the method 1's syntax might be desired later on (gameEngine?).
As a first example, we create and delete an object with clear ownership; a Scene is always owned by Blender and must not be created freely or deleted by anyone else than its owner:
import Blender scene = Blender.Scene.New('scene2') # create new empty scene scene.makeCurrent() # make active scene Blender.Scene.unlink(scene) # delete it print scene.getChildren() # invalid access, this will # throw an exception
Now we create a Lamp, which is a free object (not owned by a container):
from Blender import Lamp, Object, Scene lamp = Lamp.New('Spot') # new lamp of type 'Spot' lamp.energy = 1.8 lamp.spotSize = 30.0 # set some properties ob = Object.New('Lamp') # create Lamp Object ob.link(lamp) # link lamp data to Object sc = Scene.getCurrent() # current Scene sc.link(ob) # link object to Scene ob = Object.New('Lamp2') # create another Lamp Object ob.setLocation(10.0, 0.0, 0.0) # set location ob.link(lamp) # link with same Lamp data sc.link(ob) # and link Object to same scene
For a new object, a DataBlock is always created, so the lamp data can be accessed another way:
from Blender import Object, Scene ob = Object.New('Lamp') # create Lamp Object la = Object.getData() # get Datablock la.energy = 0.5 Scene.getCurrent().link(ob) # and make it visible in the Scene
To make the emulation of the old API possible in reasonable time, the whole Blender module is in fact a Python module, put on top of the existing (and slightly modified) C Python module.
A Blender object acquired by Python results in creation of two Wrappers:
+--------------+ +------------------+ +-------------------+ | Shadow Class | -> | Wrapper PyObject | -> | Blender datablock | +--------------+ +------------------+ +-------------------+ <Blender module> <_Blender module> <Blender C API>
In this case, the Shadow classes also provide the docstrings used
to generate this documentation.
Each shadow object class is derived from one of the base classes
defined in the
PROPOSAL: Naming convention
Member attributes should usually start with a lowercase character.
Uppercase start characters should only be used in special cases.
Underscore in names (
If the attribute starts uppercase, the method creates an object and returns a reference to it. Otherwise, an action to the object is applied, and/or a simple value or reference to an existing object is created.
For objects closely emulating certain Python objects (such as lists) the Python syntax will be mimicked as most as logical.
All functions getting or setting object properties through a rather
abstract data type (or if data hiding desired) start with
Methods doing conversion of class or object start with
It is now time for an example:
matrix = ob.getMatrix() # get matrix from object matrix.normalize() # normalize matrix - this does *not* modify # the object's original matrix. q = m.asQuat() # calculate quaternion from 'm'
Table of ContentsThis document was automatically generated on Mon Feb 25 13:52:14 2002 by HappyDoc version r1_5