The new API is closer to the data structure of Blender. It is strongly oriented on what you can visualize in the OopsWindow. There are classes for Scene, Object, Mesh, Curve etc., and functions to connect and create them.
Be sure to check the latest developments on our website: "www.blender.nl" . General information about Python is available at "www.python.org" .
001: # Keeps objects above the floor! 002: 003: import Blender 004: 005: if (Blender.bylink): 006: obj = Blender.link 007: if (obj.LocZ <0.0): obj.LocZ = 0.0Line 001 is a comment, all after the number sign "#" is ignored by the Python-interpreter. Empty lines are used to structure the source. A very important aspect in Python is that logical blocks are kept together with the same indention. It is best to use TABs for this. The first functional line is line 003: here we import the Blender module, and it provides us with the functionality to access Blenders functions.
The if clause in line 005 uses the "Blender.bylink" function to determine if the script is linked to an object. This linking is done on the left side of the ScriptButtons.
![]() |
[images/Python/LinkedScript.tga] |
Select the desired object and click "New". Then fill in the name of the script in the textfield. With the MenuButton you now can choose between "FrameChanged" and "Redraw". "FrameChanged" will execute the script, while a frame change (when you preview the animation, switch manually frames or while rendering). "Redraw" will execute the script also when you move the object interactive. In the little scene from above, the script uses "Redraw", try to move the empty below the groundplane, the script will prevent this.
The code responsible for this functionality is in lines six to seven. In line 006 we get the object data from the Blender.link function and store it into the variable "obj". In line 007, we use a second if-clause to determine if the objects location on the z-axis is below zero and if that is true we set the objects z-location to zero.
Currently scripts can be executed in two ways, scripts can be executed directly by pressing Alt-P in the Text window, and can also be attached to DataBlocks to be executed automatically when certain events occur, see the ScriptLink section.
The curtime requests returns a floating point value, which incorparates motion blur and field calculations, the curframe requests simply returns the integer value of the current frame.
If name is not specified then a new empty NMesh object will be returned, otherwise will attempt to return an NMesh derived from the Blender mesh with the same name, if a mesh with that name does not exist GetRaw returns None.
When the NMesh is created Blender will set the NMesh name, has_col and has_uvco based on the mesh read.
If the name is given PutRaw will attempt to replace the Blender mesh of that name with the nmesh, and will return None (regardless of success or failure). If a mesh with the name is in Blender, but has no users the effects are as if the name was not given (i.e. an object will be created and returned.)
The renormal flag determines whether vertex normals are recalculated. It is generally only interesting to not recalculate the vertex normals if they have been specifically modified to achieve an effect.
The nmesh.has_uvco and nmesh.has_col flags are used to determine whether or not the mesh should be created with vertex colors and/or UV coordinates.
NMesh | NMeshType |
---|---|
| |
The name field of the NMesh object allows scripts to determine
what mesh the object originally came from when it is otherwise
unknown, for example when the mesh has been obtained from an
Objects .data field.
In order to keep mesh sizes low mesh colors and UV coordinates are only stored when needed; if a mesh has colors or UV coordinates when it is accessed by the GetRaw function it will have the has_col and has_uvco flags set accordingly. Similarly, before a mesh is put back into Blender with the PutRaw functions the has_col and has_uvco flags must be set properly. The mats field contains a list of the names of the materials that are attached to the mesh indices. Note that this is not the same as the materials that are attached to objects. The PutRaw function will remake the material list, so this field can be used to switch the materials linked by the mesh. The verts field should contain a list of all the vertices that are to be in the mesh. If a vertice is listed in a face, but not present in the verts list, it will not be present in the face. |
NMFace | NMFaceType |
---|---|
| |
The v field is a list of NMVert objects, and not
a list of vertice indices. If the face is to be part
of an NMesh each of the objects should be in the
NMesh.verts list. The vertices determine the face in
clockwise ordering. Face's should have 2,3, or 4 vertices
to be stored in a mesh, face's with 2 vertices form
an edge, while faces with 3 or 4 vertices form a face
(a triangle or quad).
The col field is a list of NMCols, this list always has a length of 4, with the NMCol matching up to the NMVert in the v list with the same index. Extra objects in the list (ie. if the face has less than 4 vertices) are ignored. The mat field contains the material index for the face, if the face is part of an NMesh this value is used with the NMesh.mats list to determine the material for the face. |
NMVert | NMVertType |
---|---|
| |
If the vertice is from an NMesh that has been read with the GetRaw function the index field will be set to contain the index of the vertice within the array. This field is ignored by the PutRaw function, and exists only to allow simplification of some calculations relating to face->vertex resolution. The co, uvco, and no fields returns a special object of VectorType, this object is used to interact efficiently with Blender data structures, and can generally be used as if it is a list of floating point values, except its length cannot be changed. The uvco field contains the vertex UV coordinates for the mesh, these are the coordinates that are used by the Sticky mapping option. This field is a 3 member vector, but the last (Z) member is unused. The no field can be used to alter the vertex normals of a mesh, to change the way some calculations are made (for example rendering). A flag must be passed to the PutRaw function in order to prevent the normals from being recalculated if they have been modified for this purpose. Note that the vertex normals will still be recalculated if the user enters editmode or performs other operations on the mesh, regardless of the flag passed to the PutRaw function. |
NMCol | NMColType |
---|---|
| |
Blender/Python interfaces scripts (GUI scripts for short) essentially work by providing Blender with a set of callbacks to allow passage of events and drawing, and then the script takes control of the text window it was run from.
To iniatiate the interface the script must call the Draw.Register function to specify what script functions will be used to control the interface. Generally a draw and event function are passed, though either one can be left out.
Once the script has been registered, the draw callback will be executed (with no arguments) every time the window needs to be redrawn. Drawing uses the functions in the Blender.BGL module to allow scripts to have full control over the drawing process. Before drawing is initiated Blender sets up the OpenGL window clipping and stores its own state on the attribute stack, to prevent scripts from interfering with other parts of the Blender interface.
When the draw function is called the window matrix will be set up to be the window width/height, so the co-ordinate to pixel mapping is 1-1. Because Blender manages its windows internally, drawing should only take place inside the draw function, if an event must trigger drawing of some kind the event function should send a redraw event (see Draw.Redraw)
The script event function is called when the Blender window receives input events, and the script window has input focus (the mouse is in the window). The function is called with two arguments, the event and an extra value modifier, see the Events section below for more information.
Scripts can unregister themselves and return control to the Text editor by calling the Draw.Exit function. In the event that the script fails to provide a method to exit, the key combination Ctrl-Alt-Shift-Q will force a script to exit.
Event name(s) | Value meaning |
---|---|
____KEY (AKEY,F2KEY, etc.) |
The value is 0 or 1, 0 means a key-release, 1 means a key-press. |
PAD___ (PAD1, PADENTER, etc.) |
The value is 0 or 1, 0 means a key-release, 1 means a key-press. |
MOUSEX, MOUSEY | The value is the window coordinates of the mouse X/Y position |
LEFTMOUSE, MIDDLEMOUSE, RIGHTMOUSE | The value is 0 or 1, 0 means a button-release, 1 means a button-press. |
The list of all events is quite long, and most are fairly obvious (AKEY, BKEY, CKEY, ...)
so they have been shortened to ____KEY and PAD___, to find the exact name of an event
you can print the contents of the Draw module (or guess),
print dir(Blender.Draw)
.
Redraw events are buffered internally, so that regardless of how many redraw events are on the queue, the window is only redrawn once per queue-flush.
The second function is the event function, used to handle all of the input events. It should be a function taking two arguments, the first is the event number, and the second is the value modifier. See the Events section above for more information on what events are passed.
The third function is the button event function, which handles the events which are generated by the various button types.
Any of the functions can be passed as a None, and the Blender will take a default action for events that are not handled by a callback. At least one function must be passed for the Register function to have any effect.
When the button is pressed it will pass the event number specified by event to the Python's button event callback, assuming one was specified to the Draw.Register function.
The menu options are encoded in the options argument. Options are seperated by the '|' (Pipe) character, and each option consists of a name followed by a format code. Valid format codes are,
The default argument determines what values will initially be present in the Button object, and which menu option will initially be selected.
When the menu item is changed the button value is set to the value specified in the selected menu option and the button will pass the event number specified by event to the Python's button event callback, assuming one was specified to the Draw.Register function.
For example, if the menu options argument is "Color %t| Red %x1| Green %x2| Blue %x3", and the default is 2, then the menu will initially display "Green", and when the user selects the menu it will display 3 items ("Red", "Green", and "Blue") and the title "Color". Selecting the "Red", "Green", or "Blue" options will cause the button value to change to 1,2, or 3 respectively, and the event will be passed to the button event callback.
The type of number button is determined by the type of the initial argument, if it is an int the number button will hold integers; if it is a float, the number button will hold floating point values. The value of the Button return will range between min and max, with the initial argument determining which value is set by default.
When the button is pressed it will pass the event number specified by event to the Python's button event callback, assuming one was specified to the Draw.Register function.
The type of scrollbar is determined by the type of the initial argument, if it is an int the scrollbar will hold integers, if it is a float the scrollbar will hold floating point values. The value of the Button return will range between min and max, with the initial argument determining which value is set by default.
When the scrollbar is repositioned it will pass the event number specified by event to the Python's button event callback, assuming one was specified to the Draw.Register function. If the update argument is not passed (or True) then the events will be passed for every motion of the scrollbar, otherwise if the update argument is False the events will only be sent after the user releases the scrollbar.
The type of slider button is determined by the type of the initial argument, if it is an int the slider button will hold integers, if it is a float the slider button will hold floating point values. The value of the Button return will range between min and max, with the initial argument determining which value is set by default.
When the slider is repositioned it will pass the event number specified by event to the Python's button event callback, assuming one was specified to the Draw.Register function. If the update argument is not passed (or True) then the events will be passed for every motion of the slider, otherwise if the update argument is False the events will only be sent after the user releases the slider.
The value of the Button returned will be a string, reflecting the current state of the toggle. The initial argument will determine which value is initially present in the button. The length field specifies the maximum length string allowed to be entered in the button.
After the string has been edited it will pass the event number specified by event to the Python's button event callback, assuming one was specified to the Draw.Register function.
The value of the Button returned will be 0 or 1, reflecting the current state of the toggle. The default will determine which value is initially set.
When the button is pressed it will pass the event number specified by event to the Python's button event callback, assuming one was specified to the Draw.Register function.
Button | ButtonType |
---|---|
| |
Depending on the method with which the button was created the val field will have several different types, possible types are Int, Float, and String. |
The BGL module contains all the defines and functions for OpenGL with one exceptions. No extensions are supported, and no platform specific functions are supported. All function names remain the same as with the C OpenGL implementation, although in some cases this makes less sense, for example the ___f, ____i, ____s function variants are meaningless to Python.
The only exception to this rule is for functions that take pointer arguments. Since Python has no direct pointer access the BGL module includes a special type (Buffer) which essentially provides a wrapper around a pointer/malloc. Any OpenGL functions which take a pointer should be passed a Buffer object instead.
The BGL module is a flat wrapper, it performs no extra error checking or handling. This means that it is possible to cause crashes when using the module, namely when an OpenGL function is passed a Buffer object that is of the incorrect size.
Because Blender uses one OpenGL context, and the entire interface is drawn with OpenGL, it is important that scripts cannot inadvertently alter some critical state value. To effectively "sandbox" the scripts, during drawing Blender sets up the window to be drawn, and also pushes all OpenGL stack attributes onto the attribute stack. When the draw function returns the attributes are popped. It is important that BGL calls are only made during the draw function.
The dimensions argument should be a single integer if a one-dimensional list is to be created, or a list of dimensions if a multi-dimensional list is desired. For example, passing in [100, 100] would create a two-dimensional square buffer (with a total of 100*100=10,000 elements). Passing in [16, 16, 26] would create a three-dimensional buffer, twice as deep as it is wide or high (with a total of 16*16*32=8192 elements).
The template argument can be used to pass in a multidimensional list that will be used to initialise the values in the buffer, the template should have the same dimensions as the Buffer to be created. If no template is passed all values are initialised to zero.
Buffer | BufferType |
---|---|
| |
The Buffer object can be indexed, assigned, sliced, etc. just like Python multi-dimensional list (list of lists) with the exception that its size cannot be changed. |
If name is not specified returns a list of all the Object objects in the current scene.
Object | BlockType |
---|---|
| |
The name, block_type, and properties fields are common to all
BlockType objects.
The loc, dloc, rot, drot, size, and dsize fields all return a Vector object, which is used to interact efficiently with Blender data structures. It can generally be used as if it was a list of floating point values, but its length cannot be changed. For the parent, track, ipo, and data fields if the object does not have one the data, or the data is not accessible to python, the field returns None. |
If name is not specified returns a list of all the Lamp objects in the current scene.
Objects
Lamp | BlockType |
---|---|
| |
The name, block_type, and properties fields are common to all
BlockType objects.
If the lamp does not have an Ipo the Lamp.ipo field returns None. |
If name is not specified returns a list of all the Camera objects in the current scene.
Camera | BlockType |
---|---|
| |
The name, block_type, and properties fields are common to all
BlockType objects.
If the camera does not have an Ipo the Camera.ipo field returns None. |
If name is not specified returns a list of all the Material objects in the current scene.
Material | BlockType |
---|---|
| |
The name, block_type, and properties fields are common to all
BlockType objects.
If the material does not have an Ipo the Material.ipo field returns None. |
If name is not specified returns a list of all the World objects in the current scene.
World | BlockType |
---|---|
| |
The name, block_type, and properties fields are common to all
BlockType objects.
If the world does not have an Ipo the World.ipo field returns None. |
If name is not specified returns a list of all the Ipo objects in the current scene.
Ipo | BlockType |
---|---|
| |
The name, block_type, and properties fields are common to all BlockType objects. |
IpoCurve | IpoCurveType |
---|---|
| |
In order to be able to easily and quickly edit ipo curves,
there needs to be a mechanism to allow Blender to be able
to recalculate curve specific data, without the data being
recalculated during every script operation.
To handle this, the points field returns a list of the BezTriples that make up the curve. This list can be edited without any intervention by Blender. To update the curve, the list must be reassigned to the points field. One unfortunate side effect of this is that single points cannot simply be edited, editing IpoCurve.points[0] in place will not update the curve. The type field returns one of the following values,
The extend field returns one of the following values,
|
BezTriple | BezTripleType |
---|---|
| |
The h1, pt, and h2 fields all return a Vector object, which
is used to interact efficiently with Blender data structures. It can
generally be used as if it were a list of floating point values, but
its length cannot be changed.
The h1t and h2t fields determine the handle types, they return and can be set to the following values,
|