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

Source Code for Module API_intro

  1  # This is not a real module, it's simply an introductory text. 
  2   
  3  """ 
  4  The Blender Python API Reference 
  5  ================================ 
  6   
  7          for a full list of changes since 2.45 see U{http://wiki.blender.org/index.php/Release_Notes/Notes246/Python_API} 
  8   
  9          Top Module: 
 10          ----------- 
 11   
 12                  - L{Blender} 
 13                  - L{bpy<Bpy>} (experimental) 
 14   
 15          Submodules: 
 16          ----------- 
 17                  - L{Armature} 
 18                          - L{NLA} 
 19                          - L{Action<NLA.Action>} 
 20                  - L{BezTriple} 
 21                  - L{BGL} 
 22                  - L{Camera} 
 23                  - L{Curve} 
 24                  - L{Draw} 
 25                  - L{Effect} 
 26                  - L{Geometry} 
 27                  - L{Group} 
 28                  - L{Image} 
 29                  - L{Ipo} 
 30                  - L{IpoCurve} 
 31                  - L{Key} 
 32                  - L{Lamp} 
 33                  - L{Lattice} 
 34                  - L{Library} 
 35                  - L{Material} 
 36                  - L{Mathutils} 
 37                  - L{Mesh} 
 38                    - L{MeshPrimitives} 
 39                  - L{Metaball} 
 40                  - L{NMesh} (deprecated) 
 41                  - L{Noise} 
 42                  - L{Object} 
 43                          - L{Modifier} 
 44                          - L{Pose} 
 45                          - L{Constraint} 
 46                          - L{ActionStrips<NLA>} 
 47                  - L{Particle} 
 48                  - L{Registry} 
 49                  - L{Scene} 
 50                          - L{Radio} 
 51                          - L{Render} 
 52                  - L{Sound} 
 53                  - L{Text} 
 54                  - L{Text3d} 
 55                          - L{Font} 
 56                  - L{Texture} 
 57                  - L{TimeLine} 
 58                  - L{Types} 
 59                  - L{Window} 
 60                          - L{Theme} 
 61                  - L{World} 
 62                  - L{sys<Sys>} 
 63   
 64          Additional information: 
 65          ----------------------- 
 66                  - L{API_related}: 
 67                          - Calling scripts from command line 
 68                          - Script links and space handlers 
 69                          - How to register scripts in menus 
 70                          - Recommended ways to document and support configuration options 
 71   
 72  Introduction: 
 73  ============= 
 74   
 75          This reference documents the Blender Python API, a growing collection of 
 76          Python modules (libraries) that give access to part of the program's internal 
 77          data and functions. 
 78           
 79          Through scripting Blender can be extended in real-time via 
 80          U{Python <www.python.org>}, an impressive high level, multi-paradigm, open 
 81          source language.  Newcomers are recommended to start with the tutorial that 
 82          comes with it. 
 83   
 84          This opens many interesting possibilities, ranging from automating repetitive 
 85          tasks to adding new functionality to the program: procedural models, 
 86          importers and exporters, even complex applications and so on.  Blender itself 
 87          comes with some scripts, but many others can be found in the Scripts & Plugins 
 88          sections and forum posts at the Blender-related sites listed below. 
 89   
 90  Scripting and Blender: 
 91  ====================== 
 92   
 93  These are the basic ways to execute scripts in Blender: 
 94   
 95          1. They can be loaded or typed as text files in the Text Editor window, then 
 96          executed with ALT+P. 
 97          2. Via command line: C{blender -P <scriptname>} will start Blender and execute 
 98          the given script.  <scriptname> can be a filename in the user's file system or 
 99          the name of a text saved in a .blend Blender file: 
100          'blender myfile.blend -P textname'. 
101          3. Via command line in I{background mode}: use the '-b' flag (the order is 
102          important): C{blender -b <blendfile> -P <scriptname>}.  <blendfile> can be any 
103          .blend file, including the default .B.blend that is in Blender's home directory 
104          L{Blender.Get}('homedir'). In this mode no window will be opened and the 
105          program will leave as soon as the script finishes execution. 
106          4. Properly registered scripts can be selected directly from the program's 
107          menus. 
108          5. Scriptlinks: these are also loaded or typed in the Text Editor window and 
109          can be linked to objects, materials or scenes using the Scriptlink buttons 
110          tab.  Script links get executed automatically when their events (ONLOAD, 
111          REDRAW, FRAMECHANGED) are triggered.  Normal scripts can create (L{Text}) and 
112          link other scripts to objects and events, see L{Object.Object.addScriptLink}, 
113          for example. 
114          6. A script can call another script (that will run in its own context, with 
115          its own global dictionary) with the L{Blender.Run} module function. 
116   
117   
118  Interaction with users: 
119  ----------------------- 
120   
121          Scripts can: 
122                  - simply run and exit; 
123                  - pop messages, menus and small number and text input boxes; 
124                  - draw graphical user interfaces (GUIs) with OpenGL calls and native 
125                          program buttons, which stay there accepting user input like any other 
126                          Blender window until the user closes them; 
127                  - attach themselves to a space's event or drawing code (aka space handlers, 
128                          L{check here<API_related>}); 
129                  - make changes to the 3D View (set visible layer(s), view point, etc); 
130                  - grab the main input event queue and process (or pass to Blender) selected 
131                          keyboard, mouse, redraw events -- not considered good practice, but still 
132                          available for private use; 
133                  - tell Blender to execute other scripts (see L{Blender.Run}()); 
134                  - use external Python libraries, if available. 
135   
136          You can read the documentation for the L{Window}, L{Draw} and L{BGL} modules 
137          for more information and also check the Python site for external modules that 
138          might be useful to you.  Note though that any imported module will become a 
139          requirement of your script, since Blender itself does not bundle external 
140          modules. 
141   
142  Command line mode: 
143  ------------------ 
144   
145          Python was embedded in Blender, so to access BPython modules you need to 
146          run scripts from the program itself: you can't import the Blender module 
147          into an external Python interpreter. 
148   
149          On the other hand, for many tasks it's possible to control Blender via 
150          some automated process using scripts.  Interested readers should learn about 
151          features like "OnLoad" script links, the "-b <blendfile>" (background mode) 
152          and "-P <script>" (run script) command line options and API calls like 
153          L{Blender.Save}, L{Blender.Load}, L{Blender.Quit} and the L{Library} and 
154          L{Render} modules.  
155   
156          Note that command line scripts are run before Blender initializes its windows 
157          (and in '-b' mode no window will be initialized), so many functions that get 
158          or set window related attributes (like most in L{Window}) don't work here.  If 
159          you need those, use an ONLOAD script link (see L{Scene.Scene.addScriptLink}) 
160          instead -- it's also possible to use a command line script to write or set an 
161          ONLOAD script link.  Check the L{Blender.mode} module var to know if Blender 
162          is being executed in "background" or "interactive" mode. 
163   
164          L{Click here for command line and background mode examples<API_related>}. 
165   
166   
167  Demo mode: 
168  ---------- 
169   
170          Blender has a demo mode, where once started it can work without user 
171          intervention, "showing itself off".  Demos can render stills and animations, 
172          play rendered or real-time animations, calculate radiosity simulations and 
173          do many other nifty things.  If you want to turn a .blend file into a demo, 
174          write a script to run the show and link it as a scene "OnLoad" scriptlink. 
175          The demo will then be played automatically whenever this .blend file is 
176          opened, B{unless Blender was started with the "-y" parameter}. 
177   
178  The Game Engine API: 
179  -------------------- 
180   
181          Blender has a game engine for users to create and play 3d games.  This 
182          engine lets programmers add scripts to improve game AI, control, etc, making 
183          more complex interaction and tricks possible.  The game engine API is 
184          separate from the Blender Python API this document references and you can 
185          find its own ref doc in the doc section of the main sites below. 
186   
187  Blender Data Structures: 
188  ------------------------ 
189   
190          Programs manipulate data structures.  Blender python scripts are no exception. 
191          Blender uses an Object Oriented architecture.  The BPython interface tries to 
192          present Blender objects and their attributes in the same way you see them 
193          through the User Interface (the GUI).  One key to BPython programming is 
194          understanding the information presented in Blender's OOPS window where Blender 
195          objects and their relationships are displayed. 
196   
197          Each Blender graphic element (Mesh, Lamp, Curve, etc.) is composed from two 
198          parts: an Object and ObData. The Object holds information about the position, 
199          rotation and size of the element.  This is information that all elements have 
200          in common.  The ObData holds information specific to that particular type of 
201          element.   
202   
203          Each Object has a link to its associated ObData.  A single ObData may be 
204          shared by many Objects.  A graphic element also has a link to a list of 
205          Materials.  By default, this list is associated with the ObData. 
206   
207          All Blender objects have a unique name.  However, the name is qualified by the 
208          type of the object.  This means you can have a Lamp Object called Lamp.001 
209          (OB:Lamp.001) and a Lamp ObData called Lamp.001 (LA:Lamp.001). 
210   
211          For a more in-depth look at Blender internals, and some understanding of why 
212          Blender works the way it does, see the U{Blender Architecture document 
213          <http://www.blender3d.org/cms/Blender_Architecture.336.0.html>}. 
214   
215   
216  A note to newbie script writers: 
217  -------------------------------- 
218   
219          Interpreted languages are known to be much slower than compiled code, but for 
220          many applications the difference is negligible or acceptable.  Also, with 
221          profiling (or even simple direct timing with L{Blender.sys.time<Sys.time>}) to 
222          identify slow areas and well thought optimizations, the speed can be 
223          I{considerably} improved in many cases.  Try some of the best BPython scripts 
224          to get an idea of what can be done, you may be surprised. 
225   
226  @author: The Blender Python Team 
227  @requires: Blender 2.46 or newer. 
228  @version: 2.46 
229  @see: U{www.blender.org<http://www.blender.org>}: documentation and forum 
230  @see: U{blenderartists.org<http://blenderartists.org>}: user forum 
231  @see: U{projects.blender.org<http://projects.blender.org>} 
232  @see: U{blender architecture<http://www.blender3d.org/cms/Blender_Architecture.336.0.html>}: blender architecture document 
233  @see: U{www.python.org<http://www.python.org>} 
234  @see: U{www.python.org/doc<http://www.python.org/doc>} 
235  @see: U{Blending into Python<en.wikibooks.org/wiki/Blender_3D:_Blending_Into_Python>}: User contributed documentation, featuring a blender/python cookbook with many examples. 
236   
237  @note: the official version of this reference guide is only updated for each 
238          new Blender release.  But you can build the current SVN 
239          version yourself: install epydoc, grab all files in the 
240          source/blender/python/api2_2x/doc/ folder of Blender's SVN and use the 
241          epy_docgen.sh script also found there to generate the html docs. 
242          Naturally you will also need a recent Blender binary to try the new 
243          features.  If you prefer not to compile it yourself, there is a testing 
244          builds forum at U{blender.org<http://www.blender.org>}. 
245  """ 
246