cf620b95d5
A large chunk of documentation goodness from Campbell Barton (ideasman). Thanks! Note that any mispellings, errors, or inconsistencies are due to my ham-fisted editing.
301 lines
10 KiB
Python
301 lines
10 KiB
Python
# Blender.Scene module and the Scene PyType object
|
|
|
|
"""
|
|
The Blender.Scene submodule.
|
|
|
|
B{New}:
|
|
- L{Scene.clearScriptLinks<Scene.Scene.clearScriptLinks>} accepts a parameter now.
|
|
- acess methods L{Scene.getLayers<Scene.Scene.getLayers>}, L{Scene.setLayers<Scene.Scene.setLayers>} via lists to complement the layers and
|
|
Layers Scene attributes which use bitmasks.
|
|
- L{Scene.getActiveObject<Scene.Scene.getActiveObject>} method.
|
|
|
|
Scene
|
|
=====
|
|
|
|
This module provides access to B{Scenes} in Blender.
|
|
|
|
Example::
|
|
import Blender
|
|
from Blender import Scene, Object, Camera
|
|
#
|
|
camdata = Camera.New('ortho') # create new camera data
|
|
camdata.setName('newCam')
|
|
camdata.setLens(16.0)
|
|
scene = Scene.New('NewScene') # create a new scene
|
|
camobj = Object.New('Camera') # create a new camera object
|
|
camobj.link(camdata) # (*) link data to object first
|
|
scene.link(camobj) # and then link object to scene
|
|
scene.makeCurrent() # make this the current scene
|
|
|
|
@warn: as done in the example (*), it's recommended to first link object data to
|
|
objects and only after that link objects to scene. This is because if
|
|
there is no object data linked to an object ob, scene.link(ob) will
|
|
automatically create the missing data. This is OK on its own, but I{if
|
|
after that} this object is linked to obdata, the automatically created one
|
|
will be discarded -- as expected -- but will stay in Blender's memory
|
|
space until the program is exited, since Blender doesn't really get rid of
|
|
most kinds of data. So first linking ObData to object, then object to
|
|
scene is a tiny tiny bit faster than the other way around and also saves
|
|
some realtime memory (if many objects are created from scripts, the
|
|
savings become important).
|
|
"""
|
|
|
|
def New (name = 'Scene'):
|
|
"""
|
|
Create a new Scene in Blender.
|
|
@type name: string
|
|
@param name: The Scene name.
|
|
@rtype: Blender Scene
|
|
@return: The created Scene.
|
|
"""
|
|
|
|
def Get (name = None):
|
|
"""
|
|
Get the Scene(s) from Blender.
|
|
@type name: string
|
|
@param name: The name of a Scene.
|
|
@rtype: Blender Scene or a list of Blender Scenes
|
|
@return: It depends on the I{name} parameter:
|
|
- (name): The Scene with the given I{name};
|
|
- (): A list with all Scenes currently in Blender.
|
|
"""
|
|
|
|
def GetCurrent():
|
|
"""
|
|
Get the currently active Scene in Blender.
|
|
@rtype: Blender Scene
|
|
@return: The currently active Scene.
|
|
"""
|
|
|
|
def Unlink(scene):
|
|
"""
|
|
Unlink (delete) a Scene from Blender.
|
|
@type scene: Blender Scene
|
|
@param scene: The Scene to be unlinked.
|
|
"""
|
|
|
|
class Scene:
|
|
"""
|
|
The Scene object
|
|
================
|
|
This object gives access to Scene data in Blender.
|
|
@type name: string
|
|
@ivar name: The Scene name.
|
|
@type Layers: integer (bitmask)
|
|
@ivar Layers: The Scene layers (check also the easier to use
|
|
L{layers}). This value is a bitmask with at least
|
|
one position set for the 20 possible layers starting from the low order
|
|
bit. The easiest way to deal with these values in in hexadecimal
|
|
notation.
|
|
Example::
|
|
scene.Layers = 0x04 # sets layer 3 ( bit pattern 0100 )
|
|
scene.Layers |= 0x01
|
|
print scene.Layers # will print: 5 ( meaning bit pattern 0101)
|
|
After setting the Layers value, the interface (at least the 3d View and
|
|
the Buttons window) needs to be redrawn to show the changes.
|
|
@type layers: list of integers
|
|
@ivar layers: The Scene layers (check also L{Layers}).
|
|
This attribute accepts and returns a list of integer values in the
|
|
range [1, 20].
|
|
Example::
|
|
scene.layers = [3] # set layer 3
|
|
scene.layers = scene.layers.append(1)
|
|
print scene.layers # will print: [1, 3]
|
|
"""
|
|
|
|
def getName():
|
|
"""
|
|
Get the name of this Scene.
|
|
@rtype: string
|
|
"""
|
|
|
|
def setName(name):
|
|
"""
|
|
Set the name of this Scene.
|
|
@type name: string
|
|
@param name: The new name.
|
|
"""
|
|
|
|
def getLayers():
|
|
"""
|
|
Get the layers set for this Scene.
|
|
@rtype: list of integers
|
|
@return: a list where each number means the layer with that number is
|
|
set.
|
|
"""
|
|
|
|
def setLayers(layers):
|
|
"""
|
|
Set the visible layers for this scene.
|
|
@type layers: list of integers
|
|
@param layers: a list of integers in the range [1, 20], where each available
|
|
index makes the layer with that number visible.
|
|
@note: if this Scene is the current one, the 3D View layers are also
|
|
updated, but the screen needs to be redrawn (at least 3D Views and
|
|
Buttons windows) for the changes to be seen.
|
|
"""
|
|
|
|
def copy(duplicate_objects = 1):
|
|
"""
|
|
Make a copy of this Scene.
|
|
@type duplicate_objects: int
|
|
@param duplicate_objects: Defines how the Scene children are duplicated:
|
|
- 0: Link Objects;
|
|
- 1: Link Object Data;
|
|
- 2: Full copy.
|
|
@rtype: Scene
|
|
@return: The copied Blender Scene.
|
|
"""
|
|
|
|
def makeCurrent():
|
|
"""
|
|
Make this Scene the currently active one in Blender.
|
|
"""
|
|
|
|
def update(full = 0):
|
|
"""
|
|
Update this Scene in Blender.
|
|
@type full: int
|
|
@param full: A bool to control the level of updating:
|
|
- 0: sort the base list of objects.
|
|
- 1: sort and also regroup, do ipos, keys, script links, etc.
|
|
@warn: When in doubt, try with I{full = 0} first, since it is faster.
|
|
The "full" update is a recent addition to this method.
|
|
"""
|
|
|
|
def getRenderingContext():
|
|
"""
|
|
Get the rendering context for this scene, see L{Render}.
|
|
@rtype: RenderData
|
|
@return: the render data object for this scene.
|
|
"""
|
|
|
|
def getRadiosityContext():
|
|
"""
|
|
Get the radiosity context for this scene, see L{Radio}.
|
|
@rtype: Blender Radiosity
|
|
@return: the radiosity object for this scene.
|
|
@note: only the current scene can return a radiosity context.
|
|
"""
|
|
|
|
def getChildren():
|
|
"""
|
|
Get all objects linked to this Scene.
|
|
@rtype: list of Blender Objects
|
|
@return: A list with all Blender Objects linked to this Scene.
|
|
@note: L{Object.Get} will return all objects currently in Blender, which
|
|
means all objects from all available scenes. In most cases (exporter
|
|
scripts, for example), it's probably better to use this
|
|
scene.GetChildren instead, since it will only access objects from this
|
|
particular scene.
|
|
"""
|
|
|
|
def getActiveObject():
|
|
"""
|
|
Get this scene's active object.
|
|
@note: the active object, if selected, can also be retrieved with
|
|
L{Object.GetSelected} -- it is the first item in the returned
|
|
list. But even when no object is selected in Blender, there can be
|
|
an active one (if the user enters editmode, for example, this is the
|
|
object that should become available for edition). So what makes this
|
|
scene method different from C{Object.GetSelected()[0]} is that it can
|
|
return the active object even when no objects are selected.
|
|
@rtype: Blender Object or None
|
|
@return: the active object or None if not available.
|
|
"""
|
|
|
|
def getCurrentCamera():
|
|
"""
|
|
Get the currently active Camera for this Scene.
|
|
@note: The active camera can be any object type, not just a camera object.
|
|
@rtype: Blender Object
|
|
@return: The currently active Camera object.
|
|
"""
|
|
|
|
def setCurrentCamera(camera):
|
|
"""
|
|
Set the currently active Camera in this Scene.
|
|
@type camera: Blender Camera
|
|
@param camera: The new active Camera.
|
|
"""
|
|
|
|
def link(object):
|
|
"""
|
|
Link an Object to this Scene.
|
|
@type object: Blender Object
|
|
@param object: A Blender Object.
|
|
"""
|
|
|
|
def unlink(object):
|
|
"""
|
|
Unlink an Object from this Scene.
|
|
@type object: Blender Object
|
|
@param object: A Blender Object.
|
|
"""
|
|
|
|
def getScriptLinks (event):
|
|
"""
|
|
Get a list with this Scene's script links of type 'event'.
|
|
@type event: string
|
|
@param event: "FrameChanged", "OnLoad", "OnSave", "Redraw" or "Render".
|
|
@rtype: list
|
|
@return: a list with Blender L{Text} names (the script links of the given
|
|
'event' type) or None if there are no script links at all.
|
|
"""
|
|
|
|
def clearScriptLinks (links = None):
|
|
"""
|
|
Delete script links from this Scene. If no list is specified, all
|
|
script links are deleted.
|
|
@type links: list of strings
|
|
@param links: None (default) or a list of Blender L{Text} names.
|
|
"""
|
|
|
|
def addScriptLink (text, event):
|
|
"""
|
|
Add a new script link to this Scene.
|
|
|
|
Using OpenGL functions within a scene ScriptLink will draw graphics over the 3D view.
|
|
There is an issue with the zoom of the floating panels also scaling graphics drawn by your scriptlink.
|
|
This makes matching OpenGL graphics to mouse location impossible.
|
|
Make sure that you use floating point for operations that you would usually use int functions for: glRasterPos2f rather then glRasterPos2i.
|
|
|
|
The following example shows how you can use the OpenGL model view matrix to obtain the scale value.
|
|
|
|
Example::
|
|
from Blender import BGL
|
|
view_matrix = BGL.Buffer(BGL.GL_FLOAT, 16)
|
|
BGL.glGetFloatv(BGL.GL_MODELVIEW_MATRIX, view_matrix)
|
|
gl_scale = 1/viewMatrix[0]
|
|
|
|
# Now that we have the scale we can draw to the correct scale.
|
|
BGL.glRect2f(10*gl_scale, 10*gl_scale, 110*gl_scale, 110*gl_scale)
|
|
|
|
|
|
@type text: string
|
|
@param text: the name of an existing Blender L{Text}.
|
|
@type event: string
|
|
@param event: "FrameChanged", "OnLoad", "OnSave", "Redraw" or "Render".
|
|
"""
|
|
|
|
def play (mode = 0, win = '<VIEW3D>'):
|
|
"""
|
|
Play a realtime animation. This is the "Play Back Animation" function in
|
|
Blender, different from playing a sequence of rendered images (for that
|
|
check L{Render.RenderData.play}).
|
|
@type mode: int
|
|
@param mode: controls playing:
|
|
- 0: keep playing in the biggest 'win' window;
|
|
- 1: keep playing in all 'win', VIEW3D and SEQ windows;
|
|
- 2: play once in the biggest VIEW3D;
|
|
- 3: play once in all 'win', VIEW3D and SEQ windows.
|
|
@type win: int
|
|
@param win: window type, see L{Window.Types}. Only some of them are
|
|
meaningful here: VIEW3D, SEQ, IPO, ACTION, NLA, SOUND. But the others
|
|
are also accepted, since this function can be used simply as an
|
|
interruptible timer. If 'win' is not visible or invalid, VIEW3D is
|
|
tried, then any bigger visible window.
|
|
@rtype: bool
|
|
@return: 0 on normal exit or 1 when play back is canceled by user input.
|
|
"""
|