=IDProperties Python update=
[blender.git] / source / blender / python / api2_2x / doc / Scene.py
1 # Blender.Scene module and the Scene PyType object
2
3 """
4 The Blender.Scene submodule.
5
6 B{New}:
7   - L{Scene.clearScriptLinks<Scene.Scene.clearScriptLinks>} accepts a parameter now.
8   - acess methods L{Scene.getLayers<Scene.Scene.getLayers>}, L{Scene.setLayers<Scene.Scene.setLayers>} via lists to complement the layers and
9     Layers Scene attributes which use bitmasks. 
10   - L{Scene.getActiveObject<Scene.Scene.getActiveObject>} method.
11
12 Scene
13 =====
14
15 This module provides access to B{Scenes} in Blender.
16
17 Example::
18   import Blender
19   from Blender import Scene, Object, Camera
20   #
21   camdata = Camera.New('ortho')           # create new camera data
22   camdata.setName('newCam')
23   camdata.setLens(16.0)
24   scene = Scene.New('NewScene')           # create a new scene
25   camobj = Object.New('Camera')           # create a new camera object
26   camobj.link(camdata)                    # (*) link data to object first
27   scene.link(camobj)                      # and then link object to scene
28   scene.makeCurrent()                     # make this the current scene
29
30 @warn: as done in the example (*), it's recommended to first link object data to
31     objects and only after that link objects to scene.  This is because if
32     there is no object data linked to an object ob, scene.link(ob) will
33     automatically create the missing data.  This is OK on its own, but I{if
34     after that} this object is linked to obdata, the automatically created one
35     will be discarded -- as expected -- but will stay in Blender's memory
36     space until the program is exited, since Blender doesn't really get rid of
37     most kinds of data.  So first linking ObData to object, then object to
38     scene is a tiny tiny bit faster than the other way around and also saves
39     some realtime memory (if many objects are created from scripts, the
40     savings become important).
41 """
42
43 def New (name = 'Scene'):
44   """
45   Create a new Scene in Blender.
46   @type name: string
47   @param name: The Scene name.
48   @rtype: Blender Scene
49   @return: The created Scene.
50   """
51
52 def Get (name = None):
53   """
54   Get the Scene(s) from Blender.
55   @type name: string
56   @param name: The name of a Scene.
57   @rtype: Blender Scene or a list of Blender Scenes
58   @return: It depends on the I{name} parameter:
59       - (name): The Scene with the given I{name};
60       - ():     A list with all Scenes currently in Blender.
61   """
62
63 def GetCurrent():
64   """
65   Get the currently active Scene in Blender.
66   @rtype: Blender Scene
67   @return: The currently active Scene.
68   """
69
70 def Unlink(scene):
71   """
72   Unlink (delete) a Scene from Blender.
73   @type scene: Blender Scene
74   @param scene: The Scene to be unlinked.
75   """
76   
77 from IDProp import IDGroup, IDArray
78 class Scene:
79   """
80   The Scene object
81   ================
82    This object gives access to Scene data in Blender.
83   @ivar properties: Returns an L{IDGroup<IDProp.IDGroup>} reference to this 
84   scene's ID Properties.
85   @type properties: L{IDGroup<IDProp.IDGroup>}
86   @type name: string
87   @ivar name: The Scene name.
88   @type Layers: integer (bitmask)
89   @ivar Layers: The Scene layers (check also the easier to use
90         L{layers}).  This value is a bitmask with at least
91         one position set for the 20 possible layers starting from the low order
92         bit.  The easiest way to deal with these values in in hexadecimal 
93         notation.
94         Example::
95           scene.Layers = 0x04 # sets layer 3 ( bit pattern 0100 )
96           scene.Layers |= 0x01
97           print scene.Layers # will print: 5 ( meaning bit pattern 0101)
98         After setting the Layers value, the interface (at least the 3d View and
99         the Buttons window) needs to be redrawn to show the changes.
100   @type layers: list of integers
101   @ivar layers: The Scene layers (check also L{Layers}).
102         This attribute accepts and returns a list of integer values in the
103         range [1, 20].
104         Example::
105           scene.layers = [3] # set layer 3
106           scene.layers = scene.layers.append(1)
107           print scene.layers # will print: [1, 3]
108   @type objects: sequence of objects
109   @ivar objects: The scene's objects. The sequence supports the methods .link(ob), .unlink(ob), and .new(obdata), and can be iterated over.
110   """
111
112   def getName():
113     """
114     Get the name of this Scene.
115     @rtype: string
116     """
117
118   def setName(name):
119     """
120     Set the name of this Scene.
121     @type name: string
122     @param name: The new name.
123     """
124
125   def getLayers():
126     """
127     Get the layers set for this Scene.
128     @rtype: list of integers
129     @return: a list where each number means the layer with that number is
130        set.
131     """
132
133   def setLayers(layers):
134     """
135     Set the visible layers for this scene.
136     @type layers: list of integers
137     @param layers: a list of integers in the range [1, 20], where each available
138        index makes the layer with that number visible.
139     @note: if this Scene is the current one, the 3D View layers are also
140        updated, but the screen needs to be redrawn (at least 3D Views and
141        Buttons windows) for the changes to be seen.
142     """
143
144   def copy(duplicate_objects = 1):
145     """
146     Make a copy of this Scene.
147     @type duplicate_objects: int
148     @param duplicate_objects: Defines how the Scene children are duplicated:
149         - 0: Link Objects;
150         - 1: Link Object Data;
151         - 2: Full copy.
152     @rtype: Scene
153     @return: The copied Blender Scene.
154     """
155
156   def makeCurrent():
157     """
158     Make this Scene the currently active one in Blender.
159     """
160
161   def update(full = 0):
162     """
163     Update this Scene in Blender.
164     @type full: int
165     @param full: A bool to control the level of updating:
166         - 0: sort the base list of objects.
167         - 1: sort and also regroup, do ipos, keys, script links, etc.
168     @warn: When in doubt, try with I{full = 0} first, since it is faster.
169         The "full" update is a recent addition to this method.
170     """
171
172   def getRenderingContext():
173     """
174     Get the rendering context for this scene, see L{Render}.
175     @rtype: RenderData
176     @return: the render data object for this scene.
177     """
178
179   def getRadiosityContext():
180     """
181     Get the radiosity context for this scene, see L{Radio}.
182     @rtype: Blender Radiosity
183     @return: the radiosity object for this scene.
184     @note: only the current scene can return a radiosity context.
185     """
186
187   def getChildren():
188     """
189     Get all objects linked to this Scene.
190     @rtype: list of Blender Objects
191     @return: A list with all Blender Objects linked to this Scene.
192     @note: L{Object.Get} will return all objects currently in Blender, which
193        means all objects from all available scenes.  In most cases (exporter
194        scripts, for example), it's probably better to use this
195        scene.GetChildren instead, since it will only access objects from this
196        particular scene.
197     """
198
199   def getActiveObject():
200     """
201     Get this scene's active object.
202     @note: the active object, if selected, can also be retrieved with
203       L{Object.GetSelected} -- it is the first item in the returned
204       list.  But even when no object is selected in Blender, there can be
205       an active one (if the user enters editmode, for example, this is the
206       object that should become available for edition).  So what makes this
207       scene method different from C{Object.GetSelected()[0]} is that it can
208       return the active object even when no objects are selected.
209     @rtype: Blender Object or None
210     @return: the active object or None if not available.
211     """
212
213   def getCurrentCamera():
214     """
215     Get the currently active Camera for this Scene.
216     @note: The active camera can be any object type, not just a camera object.
217     @rtype: Blender Object
218     @return: The currently active Camera object.
219     """
220
221   def setCurrentCamera(camera):
222     """
223     Set the currently active Camera in this Scene.
224     @type camera: Blender Camera
225     @param camera: The new active Camera.
226     """
227
228   def link(object):
229     """
230     Link an Object to this Scene.
231     @type object: Blender Object
232     @param object: A Blender Object.
233     """
234
235   def unlink(object):
236     """
237     Unlink an Object from this Scene.
238     @type object: Blender Object
239     @param object: A Blender Object.
240     @rtype: boolean
241     @return: true if object was found in the scene.
242     """
243
244   def getScriptLinks (event):
245     """
246     Get a list with this Scene's script links of type 'event'.
247     @type event: string
248     @param event: "FrameChanged", "OnLoad", "OnSave", "Redraw" or "Render".
249     @rtype: list
250     @return: a list with Blender L{Text} names (the script links of the given
251         'event' type) or None if there are no script links at all.
252     """
253
254   def clearScriptLinks (links = None):
255     """
256     Delete script links from this Scene.  If no list is specified, all
257     script links are deleted.
258     @type links: list of strings
259     @param links: None (default) or a list of Blender L{Text} names.
260     """
261
262   def addScriptLink (text, event):
263     """
264     Add a new script link to this Scene.
265     
266     Using OpenGL functions within a scene ScriptLink will draw graphics over the 3D view.
267     There is an issue with the zoom of the floating panels also scaling graphics drawn by your scriptlink.
268     This makes matching OpenGL graphics to mouse location impossible.
269     Make sure that you use floating point for operations that you would usually use int functions for: glRasterPos2f rather then glRasterPos2i.
270     
271     The following example shows how you can use the OpenGL model view matrix to obtain the scale value.
272     
273     Example::
274       from Blender import BGL
275       view_matrix = BGL.Buffer(BGL.GL_FLOAT, 16)
276       BGL.glGetFloatv(BGL.GL_MODELVIEW_MATRIX, view_matrix)
277       gl_scale = 1/viewMatrix[0]
278       
279       # Now that we have the scale we can draw to the correct scale.
280       BGL.glRect2f(10*gl_scale, 10*gl_scale, 110*gl_scale, 110*gl_scale)
281       
282       
283     @type text: string
284     @param text: the name of an existing Blender L{Text}.
285     @type event: string
286     @param event: "FrameChanged", "OnLoad", "OnSave", "Redraw" or "Render".
287     """
288
289   def play (mode = 0, win = '<VIEW3D>'):
290     """
291     Play a realtime animation.  This is the "Play Back Animation" function in
292     Blender, different from playing a sequence of rendered images (for that
293     check L{Render.RenderData.play}).
294     @type mode: int
295     @param mode: controls playing:
296         - 0: keep playing in the biggest 'win' window;
297         - 1: keep playing in all 'win', VIEW3D and SEQ windows;
298         - 2: play once in the biggest VIEW3D;
299         - 3: play once in all 'win', VIEW3D and SEQ windows.
300     @type win: int
301     @param win: window type, see L{Window.Types}.  Only some of them are
302         meaningful here: VIEW3D, SEQ, IPO, ACTION, NLA, SOUND.  But the others
303         are also accepted, since this function can be used simply as an
304         interruptible timer.  If 'win' is not visible or invalid, VIEW3D is
305         tried, then any bigger visible window.
306     @rtype: bool
307     @return: 0 on normal exit or 1 when play back is canceled by user input.
308     """