[Bf-python] Suggestions for the basics of an NLA API

[Gilbert, Joseph T.]

Holy crap great work harkyman! I think this is right on target.

I would like to add something to this:
1) The placement of the NLA module is trivial. By moving the NLA_init()
you can change the module hierarchy. 
2) The movement of the NLA module is guaranteed to break scripts. The
Armature module can have a dummy NLA_init with what to change in the
code to move the script over at a minimum (if not a full mirror).
3) I propose a name change to the module. I originally named this module
NLA for better/worse but I feel that if we are moving this module to
Object (or mirroring it) the name "Animation" might make more sense than
NLA. Therefore I would propose the name "Object.Animation".

-----Original Message-----
From: bf-python-bounces at projects.blender.org
[mailto:bf-python-bounces at projects.blender.org] On Behalf Of Roland Hess
Sent: Friday, May 12, 2006 7:38 AM
To: bf-python at blender.org
Subject: [Bf-python] Suggestions for the basics of an NLA API

I put this up on pastebin, as mediawiki is down, but thought I'd send  
it to the list "for the record." I know that extending the API for  
NLA is on the todo list, and thought I'd try to provide some  
guidance, as I've worked with NLA both as a user and within the sources.

Anyway, here's my notes on what I think a bpy api for NLA ought to  
look like. Heck, I've even provided SDNA and function references, so  
writing it should be a snap for someone! Or, well, not.

Blender.Armature.NLA.ActionStrip

For the sake of clarity when dealing with the Python references, as  
well as unity between the Python API and what the user sees in the  
GUI, I recommend adding a Name space (char[32]) to the SDNA of Action  
Strips. Strip names would be shown within the strip in the NLA  
interface, and on the NLA N-key panel.

What to do about the fact that any object can now have Actions and  
Action Strips, instead of just Armatures? For now, I'd leave it  
alone. Is anyone at all using this new functionality? I'd kind of  
doubt it. My recommendation would be to leave the Py API as it is  
(under Armature) for now, then mirror it into it's own NLA module at  
a later date.

The SDNA for bActionStrip, the struct that Blender uses internally  
for Action Strips can be found in makesdna/dna_nla_types.h. In the  
sources, action strips are attached at the object level, as a  
listbase: object->nlastrips. "nlastrips" is a linked list of  
bActionStrip structs.

Armature.NLA would contain new methods to retrieve Action Strip objects:

NLA.getActionStrips()
Returns a list of all Action Strips associated with the Armature, in  
the format {name, object}.

NLA.getActionStrip("name")
Returns the Action Strip object associated with "name" parameter.

ActionStrip is a class that contains the following methods:

Methods

ActionStrip.delete()
Removes that Action Strip from the Armature's NLA list.
Deleted Action Strips are deallocated through Blender's BLI_List  
functions, destroying them. They are not just "unlinked" like other  
objects.
Function in src/editnla.c/delete_nlachannel_keys()

ActionStrip.moveUp()
Moves the Action Strip up in the Armature's NLA List.
In the sources, this is equivalent to moving the bActionStrip object  
closer to the front of the object->nlastrips list.
Function in src/editnla.c/shift_nlastrips_up()

ActionStrip.moveDown()
Moves the Action Strip down in the Armature's NLA List.
In the sources, this is equivalent to moving the bActionStrip object  
closer to the end of the object->nlastrips list.
Function in src/editnla.c/shift_nlastrips_down()

ActionStrip.resetActionLimits()
Activates the functionality found in NLA Strip menu under "Reset  
Action Start/End"
This function restores the values of ActionStart and ActionEnd to  
their defaults, usually the first and last frames within an action  
that contain keys.
Function in src/editnla.c/reset_action_strips(1);

ActionStrip.resetStripSize()
Activates the functionality found in NLA Strip menu under "Reset  
Strip Size"
This function resets the Action Strip size to it's creation values.
Function in src/editnla.c/reset_action_strips(2);

ActionStrip.snapToFrame()
Activates the functionality found in NLA Strip menu under "Snap to  
Frame"
This function snaps the ends of the action strip to the nearest whole  
numbered frame.
Function in src/editnla.c/snap_action_strips();

ActionStrip.addStrip("Name",Action Object 
[,StripStart,StripEnd,ActionStart,ActionEnd,Repeat,BlendMode,StridePath,

StrideAxis,StrideLength,Stridebone,BlendIn,BlendOut])
This function creates a new Action Strip, attached to the Armature  
object. The strip would be created at the end of the linked list of  
bActionStrips on object->nlastrips. The new Action Strip would have  
the specified "Name", and would be created pointing to the Action  
Object passed as a parameter, with whatever the default creation  
values would be if the user were doing the Add via the GUI. If the  
user wanted to, they could call the addStrip method with the  
additional parameters to have it create a custom Action Strip with  
predefined values.

Properties

ActionStrip.StripStart -- maps to "start" in SDNA
ActionStrip.StripEnd -- maps to "end" in SDNA
ActionStrip.ActionStart -- maps to "actstart" in SDNA
ActionStrip.ActionEnd -- maps to "actend" in SDNA
ActionStrip.Repeat -- maps to "repeat" in SDNA
ActionStrip.BlendMode -- maps to "mode" in SDNA
ActionStrip.StridePath -- maps to "flag" in SDNA (ACTRSTRIP_USESTRIDE)
ActionStrip.StrideAxis -- maps to "stride_axis" in SDNA
ActionStrip.StrideLength -- maps to "stridelen" in SDNA
ActionStrip.StrideBone -- maps to "stridechannel[32]" in SDNA
ActionStrip.BlendIn -- maps to "blendin" in SDNA
ActionStrip.BlendOut -- maps to "blendout" in SDNA

Altering any of these properties or calling any of the methods  
(except getStrips) should trigger an NLA window refresh.

Roland Hess
harkyman



_______________________________________________
Bf-python mailing list
Bf-python at projects.blender.org
http://projects.blender.org/mailman/listinfo/bf-python