8290173a11f08f7c0685959491b6b808ccf0c95c
[blender.git] / source / blender / python / api2_2x / doc / API_intro.py
1 # This is not a real module, it's simply an introductory text.
2
3 """
4 The Blender Python API Reference
5 ================================
6
7  An asterisk (*) means the module has been updated.
8
9  for a full list of changes since 2.42 see U{http://mediawiki.blender.org/index.php/Release_Notes/Notes243/Python_API}
10
11  Top Module:
12  -----------
13
14   - L{Blender}
15
16  Submodules:
17  -----------
18   - L{Armature} (*)
19      - L{NLA}
20      - L{Action<NLA.Action>}
21   - L{BezTriple} (*)
22   - L{BGL}
23   - L{Camera} (*)
24   - L{Curve} (*)
25   - L{Draw} (*)
26   - L{Effect}
27   - L{Geometry} (*)
28   - L{Group} (*)
29   - L{Image} (*)
30   - L{Ipo} (*)
31     - L{IpoCurve} (*)
32   - L{Key} (*)
33   - L{Lamp}
34   - L{Lattice} (*)
35   - L{Library} (*)
36   - L{Material} (*)
37   - L{Mathutils} (*)
38   - L{Mesh} (*)
39     - L{MeshPrimitives} (*)
40   - L{Metaball} (*)
41   - L{NMesh} (*)
42   - L{Noise}
43   - L{Object} (*)
44      - L{Modifier} (*)
45      - L{Pose} (*)
46      - L{Constraint} (*)
47      - L{ActionStrips<NLA>} (*)
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
67   - L{Special features<API_related>}:
68     - scripts: registering in menus, documenting, configuring (new);
69     - command line examples (new);
70     - script links (*), space handler script links, Group module (new).
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.43 or newer.
228 @version: 2.43
229 @see: U{www.blender3d.org<http://www.blender3d.org>}: main site
230 @see: U{www.blender.org<http://www.blender.org>}: documentation and forum
231 @see: U{blenderartists.org<http://blenderartists.org>}: user forum
232 @see: U{projects.blender.org<http://projects.blender.org>}
233 @see: U{blender architecture<http://www.blender3d.org/cms/Blender_Architecture.336.0.html>}: blender architecture document
234 @see: U{www.python.org<http://www.python.org>}
235 @see: U{www.python.org/doc<http://www.python.org/doc>}
236 @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.
237 @note: this documentation was generated by epydoc, which can output html and
238    pdf.  For pdf it requires a working LaTeX environment.
239
240 @note: the official version of this reference guide is only updated for each
241    new Blender release.  But you can build the current CVS
242    version yourself: install epydoc, grab all files in the
243    source/blender/python/api2_2x/doc/ folder of Blender's CVS and use the
244    epy_docgen.sh script also found there to generate the html docs.
245    Naturally you will also need a recent Blender binary to try the new
246    features.  If you prefer not to compile it yourself, there is a testing
247    builds forum at U{blender.org<http://www.blender.org>}.
248 """