[Bf-python] Suggestions for the basics of an NLA API
Roland Hess
rolandh at reed-witting.com
Fri May 12 13:38:21 CEST 2006
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
More information about the Bf-python
mailing list