BPython:

- Scripts:
    fixed error in "Save Current Theme" which prevented it from automatically updating script registration in menus.
    cosmetic changes in a couple of Campbell's sel_same.py script strings + more descriptive name for its new menu place (3d view, face mode -> select menu).
    small updates to help_browser.py script.

 The above changes are related to this:
- Added new script menu entries: Render (for exporters to renderers), Themes, FaceSelect (this already at the proper place).  Updated Scripts win->Scripts menu so it won't show all available entries, only  the ones we mean to see there.
- Updated menu registration so that scripts folders can become trees.  The release/scripts/ dir should be updated soon with subdirs like converters/, modifiers/, generators/ or whatever -- better discuss first (or is it? /me afraid of long irc discussions during meetings :) ).

- Modules:
    Blender: added 'udatadir' option to .Get() function and added var Blender.mode to tell if Blender is in bg or interactive mode.
    NMesh: added Campbell's nmesh.transform(matrix, recalc_normals = False) method (reworked, so my fault if it doesn't work).

- Bugs fixed:
    #2123: http://projects.blender.org/tracker/?func=detail&atid=125&aid=2123&group_id=9
    Reported by Ken Hughes (thanks!), who also found the exact problem later (it was in Text.Load, not with script links -- if only I had checked emails these days ... lost > 1 hour today to find the problem: passed filename to M_Text_Load was later being written over by a function called by add_text).  Also saw that Text.Load wasn't checking existence of passed filename (duh!), now it does.

    #1655: http://projects.blender.org/tracker/?func=detail&atid=125&aid=1655&group_id=9
    Reported by Chris Want (thanks!): command line "blender -P script" not working properly for bg mode ("blender -b blendfile -P script").
    Had to make some small updates to get it working (bg mode for scripts was never explicitely handled, it worked due to collateral effects, let's say), interested readers can check the report after I update it or the API_intro.py doc file.  After more testing we can make further updates.  Updated many places to not call redraws if in bg mode, now it is officially available.  Blender outputs its own info when rendering in bg mode, if that is considered a nuissance we'll have to add a few "if (during_script())" calls outside bpython.

- Removed a few warnings here and there and also updated docs.

1 files changed, 67 insertions, 18 deletions

diff --git a/source/blender/python/api2_2x/doc/API_intro.py b/source/blender/python/api2_2x/doc/API_intro.py
index 1c910711d46..8f4031756f2 100644
--- a/source/blender/python/api2_2x/doc/API_intro.py
+++ b/source/blender/python/api2_2x/doc/API_intro.py
@@ -67,22 +67,29 @@ Introduction:
 Scripting and Blender:
 ======================
 
-There are four basic ways to execute scripts in Blender:
+These are the 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
+ 2. Via command line: C{blender -P <scriptname>} will start Blender and execute
  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
+ 3. Via command line in I{background mode}: use the '-b' flag (the order is
+ important): C{blender -b <blendfile> -P <scriptname>}.  <blendfile> can be any
+ .blend file, including the default .B.blend that is in Blender's home dir
+ L{Blender.Get}('homedir'). In this mode no window will be opened and the
+ program will leave as soon as the script finishes execution.
+ 4. 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
+ 5. 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.
+ 6. A script can call another script (that will run in its own context, with
+ its own global dictionary) with the L{Blender.Run} module function.
 
 Registering scripts:
 --------------------
@@ -148,6 +155,7 @@ Interaction with users:
     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);
+  - tell Blender to execute other scripts (see L{Blender.Run}());
   - use external Python libraries, if available.
 
  You can read the documentation for the L{Window}, L{Draw} and L{BGL} modules
@@ -161,16 +169,56 @@ 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,
- for many tasks it's possible to control Blender via some automated process
- using scripts.  Note that command line scripts are run before Blender
- initializes its windows, so many functions that get or set window related
- attributes (like most in L{Window}) don't work here.  If you need those, use
- an ONLOAD script link (see L{Scene.Scene.addScriptLink}) instead -- it's
- also possible to use a command line script to write or set an ONLOAD script
- link.
+ 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, for many tasks it's possible to
+ control Blender via some automated process using scripts.  Note that command
+ line scripts are run before Blender initializes its windows (and in '-b' mode
+ no window will be initialized), so many functions that get or set window
+ related attributes (like most in L{Window}) don't work here.  If you need
+ those, use an ONLOAD script link (see L{Scene.Scene.addScriptLink}) instead --
+ it's also possible to use a command line script to write or set an ONLOAD
+ script link.  Check the L{Blender.mode} module var to know if Blender is being
+ executed in "background" or "interactive" mode.
+
+ Background mode examples::
+
+  # Open Blender in background mode with file 'myfile.blend'
+  # and run the script 'script.py':
+
+  blender -b myfile.blend -P script.py
+
+  # Note: a .blend file is always required.  'script.py' can be a file
+  # in the file system or a Blender Text stored in 'myfile.blend'.
+
+  # Let's assume 'script.py' has code to render the current frame;
+  # this line will set the [s]tart and [e]nd (and so the current) frame to
+  # frame 44 and call the script:
+
+  blender -b myfile.blend -s 44 -e 44 -P script.py
+
+  # Using now a script written to render animations, we set different
+  # start and end frames and then execute this line:
+
+  blender -b myfile.blend -s 1 -e 10 -P script.py
+
+  # Note: we can also set frames and define if we want a single image or
+  # an animation in the script body itself, naturally.
+
+ The rendered pictures will be written to the default render folder, that can
+ also be set via bpython (take a look at L{Render.RenderData}).  Their
+ names will be the equivalent frame number followed by the extension of the
+ chosen image type: 0001.png, for example.  To rename them to something else,
+ coders can use the C{rename} function in the standard 'os' Python module.
+
+ Reminder: if you just need to render, it's not necessary to have a script.
+ Blender can create stills and animations with its own command line arguments.
+ Example:
+  - a single image at frame 44: blender -b myfile.blend -f 44
+  - an animation from frame 1 to 10: blender -b myfile.blend -s 1 -e 10 -a
+
 
 Demo mode:
 ----------
@@ -263,7 +311,7 @@ Documenting scripts:
 
  Example::
    __author__ = 'Mr. Author'
-   __version__ = '1.0 11/11/04'
+   __version__ = '1.0 2005/06/06'
    __url__ = ["Author's site, http://somewhere.com",
        "Support forum, http://somewhere.com/forum/", "blender", "elysiun"]
    __email__ = ["Mr. Author, mrauthor:somewhere*com", "scripts"]
@@ -294,9 +342,10 @@ 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
- profiling to identify slow areas and well thought optimizations, the speed
- can be I{considerably} improved in many cases.  Try some of the best bpython
- scripts to get an idea of what can be done, you may be surprised.
+ profiling (or even simple direct timing with L{Blender.sys.time<Sys.time>}) to
+ identify slow areas and well thought optimizations, the speed can be
+ I{considerably} improved in many cases.  Try some of the best bpython scripts
+ to get an idea of what can be done, you may be surprised.
 
 @author: The Blender Python Team
 @requires: Blender 2.35 or newer.