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