Module Blender
[hide private]
[frames] | no frames]

Source Code for Module Blender

  1  # The Blender Module 
  2   
  3  # The module files in this folder are used to create the API documentation. 
  4  # Doc system used: epydoc - http://epydoc.sf.net 
  5  # pseudo command line (check the epy_docgen.sh file): 
  6  # epydoc -o BPY_API_23x --url "http://www.blender.org" -t Blender.py \ 
  7  # -n "Blender" --no-private --no-frames Blender.py \ 
  8  # Types.py Scene.py Object.py [ ... etc] 
  9   
 10  """ 
 11  The main Blender module. 
 12   
 13  B{New}: new var L{eventValue} for space handlers, L{Run}, L{UpdateMenus}, 
 14  new options to L{Get}, L{ShowHelp}, L{SpaceHandlers} dictionary. 
 15  L{UnpackModes} dictionary. 
 16   
 17  Blender 
 18  ======= 
 19   
 20  @type bylink: bool 
 21  @var bylink: True if the current script is being executed as a script link. 
 22  @type link: Blender Object or None; integer (space handlers) 
 23  @var link: for normal script links, 'link' points to the linked Object (can be 
 24      a scene, object (mesh, camera, lamp), material or 
 25      world).  For space handler script links, 'link' is an integer from the 
 26      Blender.L{SpaceHandlers} dictionary.  For script not running as script 
 27      links, 'link' is None. 
 28  @type event: string or int 
 29  @var event: this has three possible uses: script link type or events callback 
 30      ascii value: 
 31        - for normal script links it is a string representing the link type 
 32          (OnLoad, FrameChanged, Redraw, etc.). 
 33        - for EVENT space handler script links it is the passed event. 
 34        - for normal L{GUI<Draw.Register>} scripts I{during the events callback}, 
 35          it holds the ascii value of the current event, if it is a valid one. 
 36          Users interested in this should also check the builtin 'ord' and 'chr' 
 37          Python functions. 
 38  @type eventValue: int 
 39  @var eventValue: used only for EVENT space handlers, it holds the event value: 
 40        - for mouse button and key presses it's 1, for mouse movement 
 41          (Draw.MOUSEX and Draw.MOUSEY) it has the new x or y coordinate, resp. 
 42  @type mode: string 
 43  @var mode: Blender's current mode: 
 44      - 'interactive': normal mode, with an open window answering to user input; 
 45      - 'background': Blender was started as 'C{blender -b <blender file>}' and 
 46        will exit as soon as it finishes rendering or executing a script 
 47        (ex: 'C{blender -b <blender file> -P <script>}').  Try 'C{blender -h}' 
 48        for more detailed informations. 
 49  @type UnpackModes: constant dictionary 
 50  @var UnpackModes: dictionary with available unpack modes. 
 51      - USE_LOCAL - use files in current directory (create when necessary) 
 52      - WRITE_LOCAL - write files in current directory (overwrite when necessary) 
 53      - USE_ORIGINAL - use files in original location (create when necessary) 
 54      - WRITE_ORIGINAL - write files in original location (overwrite when necessary) 
 55  @type SpaceHandlers: constant dictionary 
 56  @var SpaceHandlers: dictionary with space handler types. 
 57      - VIEW3D_EVENT; 
 58      - VIEW3D_DRAW. 
 59  """ 
 60   
61 -def Set (request, data):
62 """ 63 Update settings in Blender. 64 @type request: string 65 @param request: The setting to change: 66 - 'curframe': the current animation frame 67 - 'compressfile' : compress file writing a blend file (Use a boolean value True/False). 68 - 'uscriptsdir': user scripts dir 69 - 'yfexportdir': yafray temp xml storage dir 70 - 'fontsdir': font dir 71 - 'texturesdir': textures dir 72 - 'seqpluginsdir': sequencer plugin dir 73 - 'renderdir': default render output dir 74 - 'soundsdir': sound dir 75 - 'tempdir': temp file storage dir 76 - 'mipmap' : Use mipmapping in the 3d view (Use a boolean value True/False). 77 @type data: int or string 78 @param data: The new value. 79 """
80
81 -def Get (request):
82 """ 83 Retrieve settings from Blender. 84 @type request: string 85 @param request: The setting data to be returned: 86 - 'curframe': the current animation frame. 87 - 'curtime' : the current animation time. 88 - 'compressfile' : compress setting from the file menu, return 0 for false or 1 for true. 89 - 'staframe': the start frame of the animation. 90 - 'endframe': the end frame of the animation. 91 - 'rt': the value of the 'rt' button for general debugging 92 - 'filename': the name of the last file read or written. 93 - 'homedir': Blender's home directory. 94 - 'datadir' : the path to the dir where scripts should store and 95 retrieve their data files, including saved configuration (can 96 be None, if not found). 97 - 'udatadir': the path to the user defined data dir. This may not be 98 available (is None if not found), but users that define uscriptsdir 99 have a place for their own scripts and script data that won't be 100 erased when a new version of Blender is installed. For this reason 101 we recommend scripts check this dir first and use it, if available. 102 - 'scriptsdir': the path to the main dir where scripts are stored. 103 - 'uscriptsdir': the path to the user defined dir for scripts. (*) 104 - 'icondir': the path to blenders icon theme files. 105 - 'yfexportdir': the path to the user defined dir for yafray export. (*) 106 - 'fontsdir': the path to the user defined dir for fonts. (*) 107 - 'texturesdir': the path to the user defined dir for textures. (*) 108 - 'texpluginsdir': the path to the user defined dir for texture plugins. (*) 109 - 'seqpluginsdir': the path to the user defined dir for sequence plugins. (*) 110 - 'renderdir': the path to the user defined dir for render output. (*) 111 - 'soundsdir': the path to the user defined dir for sound files. (*) 112 - 'tempdir': the path to the user defined dir for storage of Blender 113 temporary files. (*) 114 - 'mipmap' : Use mipmapping in the 3d view. (*) 115 - 'version' : the Blender version number. 116 @note: (*) these can be set in Blender at the User Preferences window -> File 117 Paths tab. 118 @warn: this function returns None for requested dir paths that have not been 119 set or do not exist in the user's file system. 120 @return: The requested data or None if not found. 121 """
122
123 -def GetPaths (absolute=0):
124 """ 125 Returns a list of files this blend file uses: (libraries, images, sounds, fonts, sequencer movies). 126 @type absolute: bool 127 @param absolute: When true, the absolute paths of every file will be returned. 128 @return: A list for paths (strings) that this blend file uses. 129 """
130
131 -def Redraw ():
132 """ 133 Redraw all 3D windows. 134 """
135
136 -def Load (filename = None):
137 """ 138 Load a Blender .blend file or any of the other supported file formats. 139 140 Supported formats: 141 - Blender's .blend; 142 - DXF; 143 - Open Inventor 1.0 ASCII; 144 - Radiogour; 145 - STL; 146 - Videoscape; 147 - VRML 1.0 asc. 148 149 @type filename: string 150 @param filename: the pathname to the desired file. If 'filename' 151 isn't given or if it contains the substring '.B.blend', the default 152 .B.blend file is loaded. 153 154 @warn: loading a new .blend file removes the current data in Blender. For 155 safety, this function saves the current data as an auto-save file in 156 the temporary dir used by Blender before loading a new Blender file. 157 @warn: after a call to Load(blendfile), current data in Blender is lost, 158 including the Python dictionaries. Any posterior references in the 159 script to previously defined data will generate a NameError. So it's 160 better to put Blender.Load as the last executed command in the script, 161 when this function is used to open .blend files. 162 @warn: if in edit mode, this function leaves it, since Blender itself 163 requires that. 164 @note: for all types except .blend files, this function only works in 165 interactive mode, not in background, following what Blender itself does. 166 """
167
168 -def Save (filename, overwrite = 0):
169 """ 170 Save a Blender .blend file with the current program data or export to 171 one of the builtin file formats. 172 173 Supported formats: 174 - Blender (.blend); 175 - DXF (.dxf); 176 - STL (.stl); 177 - Videoscape (.obj); 178 - VRML 1.0 (.wrl). 179 180 @type filename: string 181 @param filename: the filename for the file to be written. It must have one 182 of the supported extensions or an error will be returned. 183 @type overwrite: int (bool) 184 @param overwrite: if non-zero, file 'filename' will be overwritten if it 185 already exists (can be checked with L{Blender.sys.exists<Sys.exists>}. 186 By default existing files are not overwritten (an error is returned). 187 188 @note: The substring ".B.blend" is not accepted inside 'filename'. 189 @note: DXF, STL and Videoscape export only B{selected} meshes. 190 """
191
192 -def Run (script):
193 """ 194 Execute the given script. 195 @type script: string 196 @param script: the name of an available Blender Text (use L{Text.Get}() to 197 get a complete list) or the full pathname to a Python script file in the 198 system. 199 @note: the script is executed in its own context -- with its own global 200 dictionary -- as if it had been executed from the Text Editor or chosen 201 from a menu. 202 """
203
204 -def ShowHelp (script):
205 """ 206 Show help for the given script. This is a time-saver ("code-saver") for 207 scripts that need to feature a 'help' button in their GUIs or a 'help' 208 submenu option. With proper documentation strings, calling this function is 209 enough to present a screen with help information plus link and email buttons. 210 @type script: string 211 @param script: the filename of a registered Python script. 212 @note: this function uses L{Run} and the "Scripts Help Browser" script. This 213 means that it expects proper doc strings in the script to be able to show 214 help for it (otherwise it offers to load the script source code as text). 215 The necessary information about doc strings is L{given here<API_related>}. 216 @note: 'script' doesn't need to be a full path name: "filename.py" is enough. 217 Note, though, that this function only works for properly registered 218 scripts (those that appear in menus). 219 """
220
221 -def UpdateMenus ():
222 """ 223 Update the menus that list registered scripts. This will scan the default 224 and user defined (if available) folder(s) for scripts that have registration 225 data and will make them accessible via menus. 226 @note: only scripts that save other new scripts in the default or user 227 defined folders need to call this function. 228 """
229 -def UnpackAll (mode):
230 """ 231 Unpack all files with specified mode. 232 @param mode: The Mode for unpacking. Must be one of the modes in 233 Blender.UnpackModes dictionary. 234 @type mode: int 235 """
236 -def PackAll ():
237 """ 238 Pack all files. 239 """
240
241 -def CountPackedFiles():
242 """ 243 Returns the number of packed files. 244 """
245
246 -def Quit ():
247 """ 248 Exit from Blender immediately. 249 @warn: the use of this function should obviously be avoided, it is available 250 because there are some cases where it can be useful, like in automated 251 tests. For safety, a "quit.blend" file is saved (normal Blender behavior 252 upon exiting) when this function is called, so the data in Blender isn't 253 lost. 254 """
255 -def SaveUndoState (message):
256 """ 257 Sets an undo at the current state. 258 @param message: Message that appears in the undo menu 259 @type message: string 260 """
261