BPython:
[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}: scriptLink methods: L{Scene.getScriptLinks}, ...
7
8 Scene
9 =====
10
11 This module provides access to B{Scenes} in Blender.
12
13 Example::
14   import Blender
15   from Blender import Scene, Object, Camera
16   #
17   camdata = Camera.New('ortho')           # create new camera data
18   camdata.setName('newCam')
19   camdata.setLens(16.0)
20   scene = Scene.New('NewScene')           # create a new scene
21   camobj = Object.New('Camera')           # create a new camera object
22   camobj.link(camdata)                    # (*) link data to object first
23   scene.link(camobj)                      # and then link object to scene
24   scene.makeCurrent()                     # make this the current scene
25
26 @warn: as done in the example (*), it's recommended to first link object data to
27     objects and only after that link objects to scene.  This is because if
28     there is no object data linked to an object ob, scene.link(ob) will
29     automatically create the missing data.  This is ok on its own, but I{if
30     after that} this object is linked to obdata, the automatically created one
31     will be discarded -- as expected -- but will stay in Blender's memory
32     space until the program is exited, since Blender doesn't really get rid of
33     most kinds of data.  So first linking obdata to object, then object to
34     scene is a tiny tiny bit faster than the other way around and also saves
35     some realtime memory (if many objects are created from scripts, the
36     savings become important).
37 """
38
39 def New (name = 'Scene'):
40   """
41   Create a new Scene in Blender.
42   @type name: string
43   @param name: The Scene name.
44   @rtype: Blender Scene
45   @return: The created Scene.
46   """
47
48 def Get (name = None):
49   """
50   Get the Scene(s) from Blender.
51   @type name: string
52   @param name: The name of a Scene.
53   @rtype: Blender Scene or a list of Blender Scenes
54   @return: It depends on the I{name} parameter:
55       - (name): The Scene with the given I{name};
56       - ():     A list with all Scenes currently in Blender.
57   """
58
59 def GetCurrent():
60   """
61   Get the currently active Scene in Blender.
62   @rtype: Blender Scene
63   @return: The currently active Scene.
64   """
65
66 def Unlink(scene):
67   """
68   Unlink (delete) a Scene from Blender.
69   @type scene: Blender Scene
70   @param scene: The Scene to be unlinked.
71   """
72
73 class Scene:
74   """
75   The Scene object
76   ================
77     This object gives access to Scene data in Blender.
78   @cvar name: The Scene name.
79   """
80
81   def getName():
82     """
83     Get the name of this Scene.
84     @rtype: string
85     """
86
87   def setName(name):
88     """
89     Set the name of this Scene.
90     @type name: string
91     @param name: The new name.
92     """
93
94   def getWinSize():
95     """
96     @warn: B{Deprecated}: use RenderData.imageSizeX() and RenderData.imageSizeY()
97     """
98
99   def setWinSize(dimensions):
100     """
101     @warn: B{Deprecated}: use RenderData.imageSizeX() and RenderData.imageSizeY
102     """
103
104   def copy(duplicate_objects = 1):
105     """
106     Make a copy of this Scene.
107     @type duplicate_objects: int
108     @param duplicate_objects: Defines how the Scene children are duplicated:
109         - 0: Link Objects;
110         - 1: Link Object Data;
111         - 2: Full copy.
112     @rtype: Scene
113     @return: The copied Blender Scene.
114     """
115
116   def startFrame(frame = None):
117     """
118     @warn: B{Deprecated}: use RenderData.startFrame()
119     """
120
121   def endFrame(frame = None):
122     """
123     @warn: B{Deprecated}: use RenderData.endFrame()
124     """
125
126   def currentFrame(frame = None):
127     """
128     @warn: B{Deprecated}: use RenderData.currentFrame
129     """
130
131   def frameSettings(start = None, end = None, current = None):
132     """
133     @warn: B{Deprecated}: use RenderData.startFrame(),  RenderData.endFrame, RenderData.currentFrame
134     """
135
136   def makeCurrent():
137     """
138     Make this Scene the currently active one in Blender.
139     """
140
141   def update(full = 0):
142     """
143     Update this Scene in Blender.
144     @type full: int
145     @param full: A bool to control the level of updating:
146         - 0: sort the base list of objects.
147         - 1: sort and also regroup, do ipos, ikas, keys, script links, etc.
148     @warn: When in doubt, try with I{full = 0} first, since it is faster.
149         The "full" update is a recent addition to this method.
150     """
151
152   def getRenderdir():
153     """
154     @warn: B{Deprecated}: use RenderData.getRenderPath()
155     """
156
157   def getBackbufdir():
158     """
159     @warn: B{Deprecated}: use RenderData.getBackbufPath()
160     """
161
162   def getChildren():
163     """
164     Get all objects linked to this Scene.
165     @rtype: list of Blender Objects
166     @return: A list with all Blender Objects linked to this Scene.
167     """
168
169   def getCurrentCamera():
170     """
171     Get the currently active Camera for this Scene.
172     @rtype: Blender Camera
173     @return: The currently active Camera.
174     """
175
176   def setCurrentCamera(camera):
177     """
178     Set the currently active Camera in this Scene.
179     @type camera: Blender Camera
180     @param camera: The new active Camera.
181     """
182
183   def link(object):
184     """
185     Link an Object to this Scene.
186     @type object: Blender Object
187     @param object: A Blender Object.
188     """
189
190   def unlink(object):
191     """
192     Unlink an Object from this Scene.
193     @type object: Blender Object
194     @param object: A Blender Object.
195     """
196
197   def getScriptLinks (event):
198     """
199     Get a list with this Scene's script links of type 'event'.
200     @type event: string
201     @param event: "FrameChanged", "OnLoad" or "Redraw".
202     @rtype: list
203     @return: a list with Blender L{Text} names (the script links of the given
204         'event' type) or None if there are no script links at all.
205     """
206
207   def clearScriptLinks ():
208     """
209     Delete all this Scene's script links.
210     @rtype: bool
211     @return: 0 if some internal problem occurred or 1 if successful.
212     """
213
214   def addScriptLink (text, event):
215     """
216     Add a new script link to this Scene.
217     @type text: string
218     @param text: the name of an existing Blender L{Text}.
219     @type event: string
220     @param event: "FrameChanged", "OnLoad" or "Redraw".
221     """