BPython:
[blender.git] / source / blender / python / api2_2x / doc / API_related.py
1 # This is not a real module, it's simply an introductory text.
2
3 """
4 Blender Python related features
5 ===============================
6
7  L{Back to Main Page<API_intro>}
8
9
10 Introduction:
11 =============
12
13  This page describes special features available to BPython scripts:
14
15    - Command line mode is accessible with the '-P' and '-b' Blender options.
16    - Registration allows scripts to become available from some pre-defined menus
17      in Blender, like Import, Export, Wizards and so on.
18    - Script links are Blender Texts (scripts) executed when a particular event
19      (redraws, .blend file loading, saving, frame changed, etc.) occurs.  Now
20      there are also "Space Handlers" to draw onto or get events from a given
21      space (only 3D View now) in some window.
22    - Proper documentation data is used by the 'Scripts Help Browser' script to
23      show help information for any registered script.  Your own GUI can use
24      this facility with the L{Blender.ShowHelp} function.
25    - Configuration is for data in your script that can be tweaked according to
26      user taste or needs.  Like documentation, this is another helper
27      functionality -- you don't need to provide a GUI yourself to edit config
28      data.
29
30
31  Command line usage:
32  ===================
33
34  Specifying scripts:
35  -------------------
36
37  The '-P' option followed either by:
38    - a script filename (full pathname if not in the same folder where you run
39      the command);
40    - the name of a Text in a .blend file (that must also be specified)
41  will open Blender and immediately run the given script.
42
43  Example::
44
45   # open Blender and execute the given script:
46   blender -P script.py
47
48  Passing parameters:
49  -------------------
50
51  To pass parameters to the script you can:
52         - write them to a file before running Blender, then make your script parse that file;
53         - set environment variables and access them with the 'os' module:
54
55  Examples with parameters being passed to the script via command line::
56
57   # execute a command like:
58
59   myvar=value blender -P script.py
60
61   # and in script.py access myvar with os.getenv
62   # (os.environ and os.setenv are also useful):
63
64   # script.py:
65   import os
66   val = os.getenv('myvar')
67
68   # To pass multiple parameters, simply write them in sequence,
69   # separated by spaces:
70
71   myvar1=value1 myvar2=value2 mystr="some string data" blender -P script.py
72
73  Background mode:
74  ----------------
75
76  In '-b' mode no windows will be opened: the program will run as a command
77  line tool able to render stills and animations and execute any working Python
78  script with complete access to loaded .blend's file contents.  Once the task
79  is completed, the program will exit.
80
81  Background mode examples::
82
83   # Open Blender in background mode with file 'myfile.blend'
84   # and run the script 'script.py':
85
86   blender -b myfile.blend -P script.py
87
88   # Note: a .blend file is always required.  'script.py' can be a file
89   # in the file system or a Blender Text stored in 'myfile.blend'.
90
91   # Let's assume 'script.py' has code to render the current frame;
92   # this line will set the [s]tart and [e]nd (and so the current) frame to
93   # frame 44 and call the script:
94
95   blender -b myfile.blend -s 44 -e 44 -P script.py
96
97   # Using now a script written to render animations, we set different
98   # start and end frames and then execute this line:
99
100   blender -b myfile.blend -s 1 -e 10 -P script.py
101
102   # Note: we can also set frames and define if we want a single image or
103   # an animation in the script body itself, naturally.
104
105  The rendered pictures will be written to the default render folder, that can
106  also be set via bpython (take a look at L{Render.RenderData}).  Their
107  names will be the equivalent frame number followed by the extension of the
108  chosen image type: 0001.png, for example.  To rename them to something else,
109  coders can use the C{rename} function in the standard 'os' Python module.
110
111  Reminder: if you just need to render, it's not necessary to have a script.
112  Blender can create stills and animations with its own command line arguments.
113  Example:
114   - a single image at frame 44: blender -b myfile.blend -f 44
115   - an animation from frame 1 to 10: blender -b myfile.blend -s 1 -e 10 -a
116
117
118  Script links:
119  =============
120
121  Object script links:
122  --------------------
123
124  Users can link Blender Text scripts to some kinds of objects to have the script
125  code executed when specific events occur.  For example, if a Camera has an
126  script link set to "FrameChanged", the script will be executed whenever the
127  current frame is changed.  Links can either be manually added by users on the
128  Buttons window -> Scripts tab or created by another script (see, for example,
129  L{Object.addScriptLink<Object.Object.addScriptLink>}). 
130
131  These are the types which can be linked to scripts:
132   - Camera Data;
133   - Lamp Data;
134   - Materials;
135   - Objects;
136   - Scenes;
137   - Worlds.
138
139  And these are the available event choices:
140   - Redraw;
141   - FrameChanged;
142   - Render;
143   - OnLoad (*);
144   - OnSave (*).
145
146  (*) only available for scenes
147
148  There are three L{Blender} module variables that script link authors should
149  be aware of:
150   - B{bylink}: True if the script is running as a script link;
151   - B{link}: the object the running script was linked to (None if this is
152     not a script link);
153   - B{event}: the event type, if the running script is being executed as a
154     script link.
155
156  B{Important note about "Render" events}:
157
158  Each "Render" script link is executed twice: before rendering and after, for
159  reverting changes and for possible clean up actions.  Before rendering,
160  'Blender.event' will be "Render" and after rendering it will be "PostRender".
161  
162  This is specially useful for script links that need to generate data only
163  useful while rendering, or in case they need to switch between two mesh data
164  objects, one meant for realtime display and the other, more detailed, for
165  renders.  This pseudo-code is an example of how such scripts could be written::
166
167   import Blender
168
169   if Blender.event == "Render":
170     # prepare for rendering
171
172   elif Blender.event == "PostRender":
173     # revert changes / clean up for realtime display
174
175  Space Handler script links:
176  ---------------------------
177
178  This is a new kind of script linked to spaces in a given window.  Right now
179  only the 3D View has the necessary hooks, but the plan is to add access to
180  other types, too.  Just to clarify: in Blender, a screen is partitioned in
181  windows and each window can show any space.  Spaces are: 3D View, Text Editor,
182  Scripts, Buttons, User Preferences, Oops, etc. 
183
184  Space handlers are texts in the Text Editor, like other script links, but they
185  need to have a special header to be recognized -- B{I{the first line in the
186  text file}} must inform 1) that they are space handlers; 2) the space they
187  belong to; 3) whether they are EVENT or DRAW handlers.
188
189  Example header for a 3D View EVENT handler::
190
191   # SPACEHANDLER.VIEW3D.EVENT
192
193  Example header for a 3D View DRAW handler::
194
195   # SPACEHANDLER.VIEW3D.DRAW
196
197  EVENT space handler scripts are called by that space's event handling callback
198  in Blender.  The script receives the event B{before} it is further processed
199  by the program.  An EVENT handler script should check Blender.event (compare
200  it against L{Draw} events) and either:
201   - process it (then set Blender.event to None);
202   - ignore it.
203
204  Setting C{Blender.event = None} tells Blender not to go on processing itself
205  the event, because it was grabbed by the script.
206
207  Example::
208
209   # SPACEHANDLER.VIEW3D.EVENT
210
211   import Blender
212   from Blender import DRAW
213   evt = Blender.event
214
215   if evt == DRAW.LEFTMOUSE:
216     print "Swallowing the left mouse button press"
217   elif evt == DRAW.AKEY:
218     print "Swallowing an 'a' character"
219   else:
220     print "Let the 3D View itself process this event:", evt
221     return
222
223   # if Blender should not process itself the passed event:
224   Blender.event = None
225
226  DRAW space handlers are called by that space's drawing callback in Blender.
227  The script is called B{after} the space has been drawn.
228
229  Two of the L{Blender} module variables related to script links assume
230  different roles for space handlers:
231   - B{bylink} is the same: True if the script is running as a script link;
232   - B{link}: integer from the L{Blender}.SpaceHandlers constant dictionary,
233     tells what space this handler belongs to and the handler's type
234     (EVENT, DRAW);
235   - B{event}:
236      - EVENT handlers: an input event (check keys and mouse events in L{Draw})
237        to be processed or ignored.
238      - DRAW handlers: 0 always.
239
240  B{Guidelines}:
241   - EVENT handlers can access and change Blender objects just like any other
242     script, but they should not draw (images, polygons, etc.) to the screen,
243     use a DRAW handler to do that and if both scripts need to pass information
244     to each other, use the L{Registry} module.
245   - DRAW handlers should leave the space in the same state it was before they
246     executed.  OpenGL attributes are automatically saved (pushed) before a DRAW
247     handler runs and restored (poped) after it finishes, no need to worry about
248     that. 
249
250  Registering scripts:
251  ====================
252
253  To be registered a script needs two things:
254    - to be either in the default scripts dir or in the user defined scripts
255      path (see User Preferences window -> File Paths tab -> Python path);
256    - to have a proper header.
257
258  Try 'blender -d' to know where your default dir for scripts is, it will
259  inform either the dir or the file with that info already parsed, which is
260  in the same dir of the scripts folder.
261
262  The header should be like this one (all double and single apostrophes below
263  are required)::
264   #!BPY
265
266   # \"\"\"
267   # Name: 'Script Name'
268   # Blender: 233
269   # Group: 'Export'
270   # Submenu: 'All' all
271   # Submenu: 'Selected' sel
272   # Submenu: 'Configure (gui)' gui
273   # Tooltip: 'Export to some format.'
274   # \"\"\"
275
276  where:
277   - B{Name} is the string that will appear in the menu;
278   - B{Blender} is the minimum program version required to run the script;
279   - B{Group} defines where the script will be put, see all groups in the
280     Scripts Window's header, menu "Scripts";
281   - B{Submenu} adds optional submenus for further control;
282   - B{Tooltip} is the (short) tooltip string for the menu entry.
283
284  note:
285   - all double and single apostrophes above are required;
286   - you can "comment out" the header above, by starting lines with
287     '#', like we did.  This is not required (except for the first line, #!BPY,
288     of course), but this way the header won't conflict with Python tools that
289     you can use to generate documentation for your script code.  Just
290     remember to keep this header above any other line with triple
291     double-quotes (\"\"\") in your script.
292
293  Submenu lines are not required, use them if you want to provide extra
294  options.  To see which submenu the user chose, check the "__script__"
295  dictionary in your code: __script__['arg'] has the defined keyword (the word
296  after the submenu string name: all, sel or gui in the example above) of the
297  chosen submenu.  For example, if the user clicked on submenu 'Selected' above,
298  __script__['arg'] will be "sel".
299
300  If your script requires extra data or configuration files, there is a special
301  folder where they can be saved: see 'datadir' in L{Blender.Get}.
302
303
304  Documenting scripts:
305  ====================
306
307  The "Scripts Help Browser" script in the Help menu can parse special variables
308  from registered scripts and display help information for users.  For that,
309  authors only need to add proper information to their scripts, after the
310  registration header.
311
312  The expected variables:
313
314   - __bpydoc__ (or __doc__) (type: string):
315     - The main help text.  Write a first short paragraph explaining what the
316       script does, then add the rest of the help text, leaving a blank line
317       between each new paragraph.  To force line breaks you can use <br> tags.
318
319   - __author__ (type: string or list of strings):
320     - Author name(s).
321
322   - __version__ (type: string):
323     - Script version.  A good recommendation is using a version number followed
324       by the date in the format YYYY/MM/DD: "1.0 2005/12/31".
325
326   - __url__ (type: string or list of strings):
327     - Internet links that are shown as buttons in the help screen.  Clicking
328       them opens the user's default browser at the specified location.  The
329       expected format for each url entry is e.g.
330       "Author's site, http://www.somewhere.com".  The first part, before the
331       comma (','), is used as the button's tooltip.  There are two preset
332       options: "blender" and "elysiun", which link to the Python forums at
333       blender.org and elysiun.com, respectively.
334
335   - __email__ (optional, type: string or list of strings):
336     - Equivalent to __url__, but opens the user's default email client.  You
337       can write the email as someone:somewhere*com and the help script will
338       substitute accordingly: someone@somewhere.com.  This is only a minor help
339       to hide emails from spammers, since your script may be available at some
340       site.  "scripts" is the available preset, with the email address of the
341       mailing list devoted to scripting in Blender, bf-scripts-dev@blender.org.
342       You should only use this one if you are subscribed to the list:
343       http://projects.blender.org/mailman/listinfo/bf-scripts-dev for more
344       information.
345
346  Example::
347    __author__ = 'Mr. Author'
348    __version__ = '1.0 2005/01/01'
349    __url__ = ["Author's site, http://somewhere.com",
350        "Support forum, http://somewhere.com/forum/", "blender", "elysiun"]
351    __email__ = ["Mr. Author, mrauthor:somewhere*com", "scripts"]
352    __bpydoc__ = \"\"\"\\
353    This script does this and that.
354
355    Explaining better, this script helps you create ...
356
357    You can write as many paragraphs as needed.
358
359    Shortcuts:<br>
360      Esc or Q: quit.<br>
361      etc.
362
363    Supported:<br>
364      Meshes, metaballs.
365
366    Known issues:<br>
367      This is just an example, there's no actual script.
368
369    Notes:<br>
370      You can check scripts bundled with Blender to see more examples of how to
371     add documentation to your own works.
372  \"\"\"
373
374  B{Note}: your own GUI or menu code can display documentation by calling the
375  help browser with the L{Blender.ShowHelp} function.
376
377  Configuring scripts:
378  ====================
379
380  The L{Blender.Registry<Registry>} module provides a simplified way to keep
381  scripts configuration options in memory and also saved in config files.
382  And with the "Scripts Config Editor" script in the System menu users can later 
383  view and edit the options easily.
384
385  Let's first clarify what we mean by config options: they are simple data
386  (bools, ints, floats, strings) used by programs to conform to user
387  preferences.  The buttons in Blender's User Preferences window are a good
388  example.
389
390  For example, a particular exporter might include:
391    - SEPARATE_MATS = False: a bool variable (True / False) to determine if it
392      should write materials to a separate file;
393    - VERSION = 2: an int to define an specific version of the export format;
394    - TEX_DIR = "/path/to/textures": a default texture dir to prepend to all
395      exported texture filenames instead of their actual paths.
396
397  The script needs to provide users a GUI to configure these options -- or else
398  directly editing the source code would be the only way to change them.  And to
399  store changes made to the GUI so they can be reloaded any time the script is
400  executed, programmers have to write and load their own config files (ideally at
401  L{Blender.Get}('udatadir') or, if not available, L{Blender.Get}('datadir')).
402
403  This section describes BPython facilities (based on the L{Registry} module and
404  the config editor) that can take care of this in a simplified (and much
405  recommended) way.
406
407  Here's how it works::
408
409   # sample_exporter.py
410   import Blender
411   from Blender import Registry
412
413   # First define all config variables with their default values:
414   SEPARATE_MATERIALS = True
415   VERSION = True
416   TEX_DIR = ''
417   EXPORT_DIR = ''
418
419   # Then define a function to update the Registry:
420   def registry_update():
421     # populate a dict with current config values:
422     d = {
423       'SEPARATE_MATERIALS': SEPARATE_MATERIALS,
424       'VERSION': VERSION,
425       'TEX_DIR': TEX_DIR,
426       'EXPORT_DIR': EXPORT_DIR
427     }
428     # store the key (optional 3rd arg tells if
429     # the data should also be written to a file):
430     Registry.SetKey('sample_exporter', d, True)
431
432   # (A good convention is to use the script name as Registry key)
433
434   # Now we check if our key is available in the Registry or file system:
435   regdict = Registry.GetKey('sample_exporter', True)
436
437   # If this key already exists, update config variables with its values:
438   if regdict:
439     try:
440       SEPARATE_MATERIALS = regdict['SEPARATE_MATERIALS']
441       VERSION = regdict['VERSION']
442       TEX_DIR = regdict['TEX_DIR']
443       EXPORT_DIR = regdict['EXPORT_DIR']
444
445     # if data was corrupted (or a new version of the script changed
446     # (expanded, removed, renamed) the config vars and users may have
447     # the old config file around):
448     except: update_registry() # rewrite it
449
450   else: # if the key doesn't exist yet, use our function to create it:
451     update_registry()
452
453   # ...
454
455  Hint: nicer code than the simplistic example above can be written by keeping
456  config var names in a list of strings and using the exec function. 
457
458  B{Note}: if your script's GUI lets users change config vars, call the
459  registry_update() function in the button events callback to save the changes.
460  On the other hand, you don't need to handle configuration
461  in your own gui, it can be left for the 'Scripts Config Editor',
462  which should have access to your script's config key as soon as the
463  above code is executed once (as soon as SetKey is executed).
464
465  B{Note} (limits for config vars): strings longer than 300 characters are
466  clamped and the number of items in dictionaries, sequences and the config key
467  itself is limited to 60.
468
469
470  Scripts Configuration Editor:
471  -----------------------------
472
473  This script should be available from the System menu in the Scripts window.
474  It provides a GUI to view and edit saved configuration data, both from the
475  Registry dictionary in memory and the scripts config data dir.  This is
476  useful for all scripts with config vars, but specially for those without GUI's,
477  like most importers and exporters, since this editor will provide one for them.
478
479  The example above already gives a good idea of how the information can be
480  prepared to be accessible from this editor, but there is more worth knowing:
481
482   1. String vars that end with '_dir' or '_file' (can be upper case, too) are
483   recognized as input boxes for dirs or files and a 'browse' button is added to
484   their right side, to call the file selector.
485
486   2. Both key names and configuration variables names starting with an
487   underscore ('_') are ignored by the editor.  Programmers can use this feature
488   for any key or config var that is not meant to be configured by this editor.
489
490   3. The following information refers to extra config variables that may be
491   added specifically to aid the configuration editor script.  To clarify, in the
492   example code above these variables (the string 'script' and the dictionaries
493   'tooltips' and 'limits') would appear along with SEPARATE_MATERIALS, VERSION,
494   TEX_DIR and EXPORT_DIR, wherever they are written.
495
496   Minor note: these names are case insensitive: tooltips, TOOLTIPS, etc. are all
497   recognized.
498
499   3.1 The config editor will try to display a 'help' button for a key, to show
500   documentation for the script that owns it. To find this "owner script", it
501   will first look for a config variable called 'script', a string containing
502   the name of the owner Python file (with or without '.py' extension)::
503
504    script = 'sample_exporter.py'
505
506   If there is no such variable, the editor will check if the file formed by the
507   key name and the '.py' extension exists. If both alternatives fail, no help
508   button will be displayed.
509
510   3.2 You can define tooltips for the buttons that the editor creates for your
511   config data (string input, toggle, number sliders).  Simply create a dict
512   called 'tooltips', where config var names are keys and their tooltips,
513   values::
514
515    tooltips = {
516      'EXPORT_DIR': 'default folder where exported files should be saved',
517      'VERBOSE': 'print info and warning messages to the console',
518      'SEPARATE_MATERIALS': 'write materials to their own file'
519    }
520
521   3.3 Int and float button sliders need min and max limits.  This can be passed
522   to the editor via a dict called 'limits' (ivar1, ivar2 and fvar are meant as
523   extra config vars that might have been in the example code above)::
524
525    limits = {'ivar1': [-10, 10], 'ivar2': [0, 100], 'fvar1': [-12.3, 15.4]}
526
527   4. The Config Editor itself maintains a Registry key called "General", with
528   general options relevant to many scripts, like "verbose" to tell if the user
529   wants messages printed to the console and "confirm overwrite", to know if
530   a script should ask for confirmation before overwriting files (all exporters
531   are recommended to access the General key and check this var -- L{sys.exists
532   <Sys.exists>} tells if files or folders already exist).
533
534  Hint: for actual examples, try the ac3d importer and exporter (it's enough to
535  call them from the menus then cancel with ESC), as those have been updated to
536  use this config system.  After calling them their config data will be available
537  in the Config Editor.  We also recommend adding a section about config vars
538  in your script's help info, as done in the ac3d ones.
539
540  L{Back to Main Page<API_intro>}
541  ===============================
542 """