diff options
Diffstat (limited to 'source/blender/python/api2_2x/doc/API_intro.py')
-rw-r--r-- | source/blender/python/api2_2x/doc/API_intro.py | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/source/blender/python/api2_2x/doc/API_intro.py b/source/blender/python/api2_2x/doc/API_intro.py new file mode 100644 index 00000000000..ab9074a488e --- /dev/null +++ b/source/blender/python/api2_2x/doc/API_intro.py @@ -0,0 +1,198 @@ +# This is not a real module, it's simply an introductory text. + +""" +The Blender Python API Reference +================================ + + Top Module: + ----------- + + - L{Blender} (*) + + Submodules: + ----------- + - L{Armature} + - L{Bone} + - L{NLA} + - L{BGL} + - L{Camera} (*) + - L{Curve} + - L{Draw} (*) + - L{Effect} + - L{Image} (*) + - L{Ipo} + - L{Lamp} (*) + - L{Lattice} + - L{Library} + - L{Material} (*) + - L{Mathutils} + - L{Metaball} (*) + - L{NMesh} + - L{Noise} + - L{Object} (*) + - L{Registry} + - L{Scene} (*) + - L{Radio} (new) + - L{Render} + - L{Text} + - L{Texture} + - L{Types} + - L{Window} (* important: L{Window.EditMode}) + - L{World} (*) + - L{sys<Sys>} (*) + + (*) - marks updated. + +Introduction: +============= + + This reference documents the Blender Python API, a growing collection of + Python modules (libraries) that give access to part of the program's internal + data and functions. + + Through scripting Blender can be extended in realtime via + U{Python <www.python.org>}, an impressive high level, multi-paradigm, open + source language. Newcomers are recommended to start with the tutorial that + comes with it. + + This opens many interesting possibilities, ranging from automating repetitive + tasks to adding new functionality to the program: procedural models, + importers and exporters, even complex applications and so on. Blender itself + comes with some scripts, but many others can be found in the Scripts & Plugins + sections and forum posts at the Blender-related sites listed below. + +Scripting and Blender: +====================== + +There are four basic ways to execute scripts in Blender: + + 1. They can be loaded or typed as text files in the Text Editor window, then + executed with ALT+P. + 2. Via command line: 'blender -P <scriptname>' will start Blender and executed + the given script. <scriptname> can be a filename in the user's file system or + the name of a text saved in a .blend Blender file: + 'blender myfile.blend -P textname'. + 3. Properly registered scripts can be selected directly from the program's + menus. + 4. Scriptlinks: these are also loaded or typed in the Text Editor window and + can be linked to objects, materials or scenes using the Scriptlink buttons + tab. Script links get executed automatically when their events (ONLOAD, + REDRAW, FRAMECHANGED) are triggered. Normal scripts can create (L{Text}) and + link other scripts to objects and events, see L{Object.Object.addScriptLink}, + for example. + +Registering scripts: +-------------------- + To be registered a script needs two things: + - be either in the default scripts dir or in the user defined scripts path + (see Info window, paths tab); + - have a proper header. + + Try 'blender -d' to know where your default dir for scripts is, it will + inform either the dir or the file with that info already parsed, which is + in the same dir of the scripts folder. + + The header should be like this one (all double and single apostrophes below + are required):: + #!BPY + \"\"\" + Name: 'Script Name' + Blender: 233 + Group: 'Export' + Submenu: 'All' all + Submenu: 'Selected' sel + Submenu: 'Configure (gui)' gui + Tooltip: 'Export to some format.' + \"\"\" + + where: + - B{Name} is the string that will appear in the menu; + - B{Blender} is the minimum program version required to run the script; + - B{Group} defines where the script will be put, see all groups in the + Scripts Window's header, menu "Scripts"; + - B{Submenu} adds optional submenus for further control; + - B{Tooltip} is the (short) tooltip string for the menu entry. + + Submenu lines are not required, use them if you want to provide extra + options. To see which submenu the user chose, check the "__script__" + dictionary in your code: __script__['arg'] has the defined keyword (the word + after the submenu string name: all, sel or gui in the example above) of the + chosen submenu. For example, if the user clicked on submenu 'Selected' above, + __script__['arg'] will be "sel". + + If your script requires extra data or configuration files, there is a special + folder where they can be saved: see 'datadir' in L{Blender.Get}. + +Interaction with users: +----------------------- + + Scripts can: + - simply run and exit; + - grab the main input event queue and process (or pass to Blender) selected + keyboard, mouse, redraw events; + - pop messages, menus and small number and text input boxes; + - draw graphical user interfaces (guis) with OpenGL calls and native + program buttons, which stay there accepting user input like any other + Blender window until the user closes them; + - make changes to the 3D View (set visible layer(s), view point, etc); + - use external Python libraries, if available. + + You can read the documentation for the L{Window}, L{Draw} and L{BGL} modules + for more information and also check Python's site for external modules that + might be useful to you. Note though that any imported module will become a + requirement of your script, since Blender itself does not bundle external + modules. + +Command line mode: +------------------ + + Python was embedded in Blender, so to access bpython modules you need to + run scripts from the program itself: you can't import the Blender module + into an external Python interpreter. But with "OnLoad" script links, the + "-b" background mode and additions like the "-P" command line switch, + L{Blender.Save}, L{Blender.Load}, L{Blender.Quit} and the L{Library} module, + it's possible to control Blender from outside via some automated process + using scripts. + +Demo mode: +---------- + + Blender has a demo mode, where once started it can work without user + intervention, "showing itself off". Demos can render stills and animations, + play rendered or realtime animations, calculate radiosity simulations and + do many other nifty things. If you want to turn a .blend file into a demo, + write a script to run the show and link it as a scene "OnLoad" scriptlink. + The demo will then be played automatically whenever this .blend file is + opened, B{unless Blender was started with the "-y" parameter}. + +The Game Engine API: +-------------------- + + Blender has a game engine for users to create and play 3d games. This + engine lets programmers add scripts to improve game AI, control, etc, making + more complex interaction and tricks possible. The game engine API is + separate from the Blender Python API this document references and you can + find its own ref doc in the docs section of the main sites below. + +A note to newbie script writers: +-------------------------------- + + Interpreted languages are known to be much slower than compiled code, but for + many applications the difference is negligible or acceptable. Also, with well + thought optimizations, it can be I{considerably} reduced in many cases. Try + some of the best bpython scripts to get an idea of what can be done, it may + surprise you. + +@author: The Blender Python Team +@requires: Blender 2.34 or newer. +@version: 2.34 +@see: U{www.blender3d.org<http://www.blender3d.org>}: main site +@see: U{www.blender.org<http://www.blender.org>}: documentation and forum +@see: U{www.elysiun.com<http://www.elysiun.com>}: user forum +@see: U{projects.blender.org<http://projects.blender.org>} +@see: U{www.python.org<http://www.python.org>} +@see: U{www.python.org/doc<http://www.python.org/doc>} +@note: this documentation was generated by epydoc, which can output html and + pdf (requires a working LaTeX environment) versions of this text. +""" + |