1
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
11 Scene
12 =====
13
14 This module provides access to B{Scenes} in Blender.
15
16 Example::
17 import Blender
18 from Blender import Scene, Object, Camera
19 #
20 camdata = Camera.New('persp') # create new camera data
21 camdata.name = 'newCam'
22 camdata.lens = 16.0
23 scene = Scene.New('NewScene') # create a new scene
24 scene.objects.new(camdata,'Camera') # add a new object to the scene with newly-created data
25 scene.makeCurrent() # make this the current scene
26
27 @warn: B{scene.objects.new} is the preferred way to add new objects to a scene.
28 The older way is to create an object with B{Object.New()}, link the
29 data to the new object, then link the object to the scene. This way is
30 not recommended since a forgotten step or run-time error in the script can
31 cause bad things to be done to Blender's database.
32
33 If you use this older method, it's recommended to always perform the
34 operations in this order. This is because if
35 there is no object data linked to an object B{ob}, B{scene.link(ob)} will
36 automatically create the missing data. This is OK on its own, but I{if
37 after that} object B{ob} is linked to obdata, the automatically created one
38 will be discarded -- as expected -- but will stay in Blender's memory
39 space until the program is exited, since Blender doesn't really get rid of
40 most kinds of data. So first linking ObData to object, then object to
41 scene is a tiny tiny bit faster than the other way around and also saves
42 some realtime memory (if many objects are created from scripts, the
43 savings become important).
44 """
45
46 -def New (name = 'Scene'):
47 """
48 Create a new Scene in Blender.
49 @type name: string
50 @param name: The Scene name.
51 @rtype: Blender Scene
52 @return: The created Scene.
53 """
54
55 -def Get (name = None):
56 """
57 Get the Scene(s) from Blender.
58 @type name: string
59 @param name: The name of a Scene.
60 @rtype: Blender Scene or a list of Blender Scenes
61 @return: It depends on the I{name} parameter:
62 - (name): The Scene with the given I{name};
63 - (): A list with all Scenes currently in Blender.
64 """
65
67 """
68 Get the currently active Scene in Blender.
69 @rtype: Blender Scene
70 @return: The currently active Scene.
71 """
72
74 """
75 Unlink (delete) a Scene from Blender.
76 @type scene: Blender Scene
77 @param scene: The Scene to be unlinked.
78 """
79
80 from IDProp import IDGroup, IDArray
82 """
83 The Scene object
84 ================
85 This object gives access to Scene data in Blender.
86 @type Layers: integer (bitmask)
87 @ivar Layers: The Scene layers (check also the easier to use
88 L{layers}). This value is a bitmask with at least
89 one position set for the 20 possible layers starting from the low order
90 bit. The easiest way to deal with these values in in hexadecimal
91 notation.
92 Example::
93 scene.Layers = 0x04 # sets layer 3 ( bit pattern 0100 )
94 scene.Layers |= 0x01
95 print scene.Layers # will print: 5 ( meaning bit pattern 0101)
96 After setting the Layers value, the interface (at least the 3d View and
97 the Buttons window) needs to be redrawn to show the changes.
98 @type layers: list of integers
99 @ivar layers: The Scene layers (check also L{Layers}).
100 This attribute accepts and returns a list of integer values in the
101 range [1, 20].
102 Example::
103 scene.layers = [3] # set layer 3
104 scene.layers = scene.layers.append(1)
105 print scene.layers # will print: [1, 3]
106 @type objects: sequence of objects
107 @ivar objects: The scene's objects. The sequence supports the methods .link(ob), .unlink(ob), and .new(obdata), and can be iterated over.
108 @type cursor: Vector (wrapped)
109 @ivar cursor: the 3d cursor location for this scene.
110 @type camera: Camera or None
111 @ivar camera: The active camera for this scene (can be set)
112 @type world: World or None
113 @ivar world: The world that this scene uses (if any)
114 @type timeline: Timeline
115 @ivar timeline: The L{timeline<TimeLine.TimeLine>} for this scene, named markers are stored here. (read only)
116 @type render: RenderData
117 @ivar render: The scenes L{render<Render.RenderData>} settings. (read only)
118 @type radiosity: RenderData
119 @ivar radiosity: The scenes L{radiosity<Radio>} settings. (read only)
120 @type halfFloat: OpenEXR's half float option
121 @ivar halfFloat: boolean
122 @type zbuf: OpenEXR's save zbuf option
123 @ivar zbuf: boolean
124 @type preview: OpenEXR's save preview option
125 @ivar preview: boolean
126 @type touch: enable creating empty image files while they are rendered.
127 @ivar touch: boolean
128 @type noOverwrite: Skip rendering existing image files
129 @ivar noOverwrite: boolean
130 """
131
133 """
134 Get the name of this Scene.
135 @rtype: string
136 """
137
139 """
140 Set the name of this Scene.
141 @type name: string
142 @param name: The new name.
143 """
144
146 """
147 Get the layers set for this Scene.
148 @rtype: list of integers
149 @return: a list where each number means the layer with that number is set.
150 """
151
153 """
154 Set the visible layers for this scene.
155 @type layers: list of integers
156 @param layers: a list of integers in the range [1, 20], where each available
157 index makes the layer with that number visible.
158 @note: if this Scene is the current one, the 3D View layers are also
159 updated, but the screen needs to be redrawn (at least 3D Views and
160 Buttons windows) for the changes to be seen.
161 """
162
163 - def copy(duplicate_objects = 1):
164 """
165 Make a copy of this Scene.
166 @type duplicate_objects: int
167 @param duplicate_objects: Defines how the Scene children are duplicated:
168 - 0: Link Objects;
169 - 1: Link Object Data;
170 - 2: Full copy.
171 @rtype: Scene
172 @return: The copied Blender Scene.
173 """
174
176 """
177 Make this Scene the currently active one in Blender.
178 """
179
181 """
182 Update this Scene in Blender.
183 @type full: int
184 @param full: A bool to control the level of updating:
185 - 0: sort the base list of objects.
186 - 1: sort and also regroup, do ipos, keys, script links, etc.
187 @warn: When in doubt, try with I{full = 0} first, since it is faster.
188 The "full" update is a recent addition to this method.
189 """
190
192 """
193 Get the rendering context for this scene, see L{Render}.
194 @rtype: RenderData
195 @return: the render data object for this scene.
196 """
197
199 """
200 Get the radiosity context for this scene, see L{Radio}.
201 @rtype: Blender Radiosity
202 @return: the radiosity object for this scene.
203 @note: only the current scene can return a radiosity context.
204 """
205
207 """
208 Get all objects linked to this Scene. (B{deprecated}). B{Note}: new scripts
209 should use the L{objects} attribute instead. In cases where a list is
210 required use list(scn.objects).
211 @rtype: list of Blender Objects
212 @return: A list with all Blender Objects linked to this Scene.
213 @note: L{Object.Get} will return all objects currently in Blender, which
214 means all objects from all available scenes. In most cases (exporter
215 scripts, for example), it's probably better to use this
216 scene.GetChildren instead, since it will only access objects from this
217 particular scene.
218 @warn: Depricated! use scene.objects instead.
219 """
220
222 """
223 Get this scene's active object.
224 @note: the active object, if selected, can also be retrieved with
225 L{Object.GetSelected} -- it is the first item in the returned
226 list. But even when no object is selected in Blender, there can be
227 an active one (if the user enters editmode, for example, this is the
228 object that should become available for edition). So what makes this
229 scene method different from C{Object.GetSelected()[0]} is that it can
230 return the active object even when no objects are selected.
231 @rtype: Blender Object or None
232 @return: the active object or None if not available.
233 @warn: Depricated! use scene.objects.active instead.
234 """
235
237 """
238 Get the currently active Camera for this Scene.
239 @note: The active camera can be any object type, not just a camera object.
240 @rtype: Blender Object
241 @return: The currently active Camera object.
242 """
243
245 """
246 Set the currently active Camera in this Scene.
247 @type camera: Blender Camera
248 @param camera: The new active Camera.
249 """
250
252 """
253 Link an Object to this Scene.
254 @type object: Blender Object
255 @param object: A Blender Object.
256 """
257
259 """
260 Unlink an Object from this Scene.
261 @type object: Blender Object
262 @param object: A Blender Object.
263 @rtype: boolean
264 @return: true if object was found in the scene.
265 """
266
268 """
269 Get a list with this Scene's script links of type 'event'.
270 @type event: string
271 @param event: "FrameChanged", "OnLoad", "OnSave", "Redraw" or "Render".
272 @rtype: list
273 @return: a list with Blender L{Text} names (the script links of the given
274 'event' type) or None if there are no script links at all.
275 """
276
278 """
279 Delete script links from this Scene. If no list is specified, all
280 script links are deleted.
281 @type links: list of strings
282 @param links: None (default) or a list of Blender L{Text} names.
283 """
284
286 """
287 Add a new script link to this Scene.
288
289 Using OpenGL functions within a scene ScriptLink will draw graphics over the 3D view.
290 There is an issue with the zoom of the floating panels also scaling graphics drawn by your scriptlink.
291 This makes matching OpenGL graphics to mouse location impossible.
292 Make sure that you use floating point for operations that you would usually use int functions for: glRasterPos2f rather then glRasterPos2i.
293
294 The following example shows how you can use the OpenGL model view matrix to obtain the scale value.
295
296 Example::
297 from Blender import BGL
298 view_matrix = BGL.Buffer(BGL.GL_FLOAT, 16)
299 BGL.glGetFloatv(BGL.GL_MODELVIEW_MATRIX, view_matrix)
300 gl_scale = 1/viewMatrix[0]
301
302 # Now that we have the scale we can draw to the correct scale.
303 BGL.glRect2f(10*gl_scale, 10*gl_scale, 110*gl_scale, 110*gl_scale)
304
305
306 @type text: string
307 @param text: the name of an existing Blender L{Text}.
308 @type event: string
309 @param event: "FrameChanged", "OnLoad", "OnSave", "Redraw" or "Render".
310 """
311
312 - def play (mode = 0, win = '<VIEW3D>'):
313 """
314 Play a realtime animation. This is the "Play Back Animation" function in
315 Blender, different from playing a sequence of rendered images (for that
316 check L{Render.RenderData.play}).
317 @type mode: int
318 @param mode: controls playing:
319 - 0: keep playing in the biggest 'win' window;
320 - 1: keep playing in all 'win', VIEW3D and SEQ windows;
321 - 2: play once in the biggest VIEW3D;
322 - 3: play once in all 'win', VIEW3D and SEQ windows.
323 @type win: int
324 @param win: window type, see L{Window.Types}. Only some of them are
325 meaningful here: VIEW3D, SEQ, IPO, ACTION, NLA, SOUND. But the others
326 are also accepted, since this function can be used simply as an
327 interruptible timer. If 'win' is not visible or invalid, VIEW3D is
328 tried, then any bigger visible window.
329 @rtype: bool
330 @return: 0 on normal exit or 1 when play back is canceled by user input.
331 """
332
333 import id_generics
334 Scene.__doc__ += id_generics.attributes
335
336
338 """
339 The SceneObjects (Scene ObjectSeq) object
340 =========================================
341 This object gives access to the Objects in a Scene in Blender.
342
343 Example::
344 from Blender import Scene
345 scn = Scene.GetCurrent()
346
347 scn.objects.selected = [] # select none
348 scn.objects.selected = scn.objects # select all
349 scn.objects.context = scn.objects # select all and move into the scenes display layer
350
351 # get a list of mesh objects
352 obs = [ob for ob in scn.objects if ob.type == 'Mesh']
353
354 # Select only these mesh objects
355 scn.objects.selected = obs
356
357 # print all object names
358 for ob in scn.objects: print ob.name
359
360 # make a list of objects that you can add and remove to
361 # will not affect the current scene
362 scene_obs = list(scn.objects)
363
364 @ivar selected: an iterator over all the selected objects in a scene.
365 @type selected: sequence of L{Object}
366 @ivar context: an iterator over all the visible selected objects in a scene.
367 @type context: sequence of L{Object}
368 @ivar active: the active object in the scene.
369 @type active: L{Object}
370 @ivar camera: the active camera in the scene.
371 @type camera: L{Object}
372 """
373
375 """
376 Adds a new object to the scene. Data is either object data such as a
377 L{Mesh} or L{Curve}, or the string "Empty" for an Empty object. The
378 type of the object is determined by the type of the data.
379 @type data: string or object data
380 @param data: the object data for the new object
381 @return: the new object.
382 @rtype: L{Object}
383 """
384
386 """
387 Adds an existing object to the scene. If the object is already linked
388 to the scene, no action is taken and no exception is raised.
389 @type object: L{Object}
390 @param object: the object
391 @rtype: None
392 """
393
395 """
396 Removes an object from the scene. If the object is not linked
397 to the scene, no action is taken and no exception is raised.
398 @type object: L{Object}
399 @param object: the object
400 @rtype: None
401 """
402