[Bf-committers] Patch 6161 - Internals Tracing

[Early Ehlinger]

==== Purpose: ====
This patch introduces 3 Blender.Set-based variables to allow python 
scripts to get verbose feedback of the progress of certain functions 
sent to the terminal/console .  It is designed to be extensible, 
filterable, and quiet by default.

==== Why? ====
The initial set of traces provided in the patch are useful for producing 
highly verbose progress messages during a render session.  These can be 
captured on a render farm and sent to a central render log for later 
analysis, for example.  

It is our hope that additional trace groups are added by developers of 
various subsystems in the future, e.g., for fluidsim, physics 
calculations, etc., so that if somebody wants verbose progress messages, 
they can get them.

==== Usage: ====
To turn on tracing, one would write a Python script similar to this:

  def traceCallback( sFile , nLine , sMessage , nFilter ):
    print sFile , "(" , nLine , ") [" , nFilter , "] - " , sMessage;

  import Blender;
  Blender.Set( "traceCallback" , traceCallback );

To turn tracing off, the script would then do this:

  Blender.Set( "traceCallback" , None );

You can enable/disable specific groups of callbacks as well:

  Blender.Set( "traceFilterOn"  , 0 ); # turn on debug messages.
  Blender.Set( "traceFilterOff" , 0 ); # turn off debug messages.

  Blender.Set( "traceFilterOn"  , 1 ); # turn on render progress messages.
  Blender.Set( "traceFilterOff" , 1 ); # turn off render progress messages.

There are 3 groups provided in this patch:
  0 - debug
  1 - render progress
  2 - unpack progress

==== Patch Details: ====
This patch comes in the form of a .zip file, because I assume I do not 
have permission to add a .h file to the repository.  unzip it in the 
root of the blender source tree (right above the blender and lib 
folders), and the Blender_Trace.h file should go in the right spot.

The other file in the patch is a standard cvs diff -b -u > 
blender_trace.patch

The main file affected is the python/2_2x/Blender.c file.  This patch 
adds 2 global variables: g_blender_trace_callback, and 
g_blender_trace_filter[].  It also adds a function, Blender_Trace, that 
can be called like printf to route messages to g_blender_trace_callback 
(a python function), and the hooks to access this functionality from 
Python.  

==== Rationale ====
I originally planned to have traceFilter take a "bitwise-or"'d group of 
flags that would then be stored and compared during a call to 
Blender_Trace.  Upon further consideration, I decided to have 
traceFilter represent an array of groups rather than a bit-flag since 
there is the potential for wanting more than 32 or even 64 individual 
groups.

-- Early Ehlinger, President, ResPower, Inc.