Composition Members
Composition
Represents an composition.
The Composition object’s methods and members are directly available in the console and in comp scripts written in Lua.
Composition Attributes
| Attribute Name | Type | Description |
|---|---|---|
| COMPN_CurrentTime | number | This is the current time that the composition is at. This is the time that the user will see, and any modifications that do not specify a time will set a keyframe at this time. |
| COMPB_HiQ | boolean | Indicates if the composition is currently in ‘HiQ’ mode or not. |
| COMPB_Proxy | boolean | Indicates if the composition is currently in ‘Proxy’ mode or not. |
| COMPB_Rendering | integer | Indicates if the composition is currently rendering. |
| COMPN_RenderStart | number | The render start time of the composition. A render with no start specified will begin from this time. |
| COMPN_RenderEnd | number | The render end time of the composition. A render with no end specified will render this frame last. |
| COMPN_GlobalStart | number | The global start time of the comp. This is the start of time at which the composition is valid. Anything before this cannot be rendered or evaluated. |
| COMPN_GlobalEnd | number | The global end time of the composition. This is the end of time at which the comp is valid. Anything after this cannot be rendered or evaluated. |
| COMPN_LastFrameRendered | number | The most recent frame that has been successfully completed during a render. |
| COMPN_LastFrameTime | number | The amount of time taken to render the most recently completed frame, in seconds. |
| COMPN_AverageFrameTime | number | The average amount of time taken to render each frame to this point of the render, in seconds. |
| COMPN_TimeRemaining | number | An estimation of how much more time will be needed to complete this render, in seconds. |
| COMPS_FileName | string | The full path and name of the composition file. |
| COMPS_Name | string | The name of the composition. |
| COMPI_RenderFlags | integer | The flags specified for the current render. |
| COMPI_RenderStep | integer | The step value being used for the current render. |
| COMPB_Locked | boolean | This indicates if the composition is currently locked. |
AbortRender()
Stops any current rendering.
AbortRenderUI()
Asks the user before aborting the render
ActiveTool [read-only]
Represents the currently active tool on this comp
Getting: tool = Composition.ActiveTool – (Tool)
AddMedia()
AddSettingAction()
Adds a .settings to the comp
AddTool(id[, defsettings][, xpos][, ypos])
Adds a tool to the comp at a given position
Parameters:
id (string) – id
defsettings (boolean) – defsettings
xpos (number) – xpos
ypos (number) – ypos
Returns: tool
Return type: Tool
??? note
**id** the RegID of the tool to add.
**defsettings** specifies whether user-modified default settings should be applied for the new tool (true) or not (false, default).
**xpos** the X position of the tool in the flow view.
**ypos** the Y position of the tool in the flow view.
You can use the number -32768 (the smallest negative value of a 16-bit integer) for both x and y position. This will cause Fusion to add the tool as if you had clicked on one of the toolbar icons. The tool will be positioned next to the currently selected one and a connection will automatically be made if possible. If no tool is selected then the last clicked position on the flow will be used. The same behaviour can be achieved with the comp:AddToolAction method.
**Returns** a tool handle that can be used to control the newly added tool.
AddToolAction(id[, xpos][, ypos])
Adds a tool to the comp.
Parameters:
id (string) – id
xpos (number) – xpos
ypos (number) – ypos
Returns: tool
Return type: Tool
Note
If no positions are given it will cause Fusion to add the tool as if you had clicked on one of the toolbar icons. The tool will be positioned next to the currently selected one and a connection will automatically be made if possible. If no tool is selected then the last clicked position on the flow will be used.
AskRenderSettings()
Show the Render Settings dialog.
AskUser(title, controls)
Present a custom dialog to the user, and return selected values
The AskUser function displays a dialog to the user, requesting input using a variety of common fusion controls such as sliders, menus and textboxes. All script execution stops until the user responds to the dialog by selecting OK or Cancel. This function can only be called interactively, command line scripts cannot use this function.
The second argument of this function recieves a table of inputs describing which controls to display. Each entry in the table is another table describing the control and its options. For example, if you wanted to display a dialog that requested a path from a user, you might use the following script.
Returns a table containing the responses from the user, or nil if the user cancels the dialog.
AutoPos [Read-Write]
Enable autoupdating of XPos/YPos when adding tools.
Getting: val = Composition.AutoPos – (boolean)
Setting: Composition.AutoPos = val – (boolean)
ChooseAction()
Displays a dialog with a list of selectable actions
ChooseTool()
Displays a dialog with a list of selectable tools
ClearUndo()
Clears the Undo/Redo history
Close()
Close the composition
Copy()
Copy a list of tools to the Clipboard
CopySettings()
Copy a list of tools to a settings table
CurrentFrame [Read-Only]
Represents the currently active frame for this composition
Do not confuse with CurrentTime.
Getting:
CurrentTime [Read-Write]
The current time position for this composition
Getting:
Setting:
DisableSelectedTools()
Pass-through the selected tools
EndUndo()
The StartUndo() function is always paired with an EndUndo() function. Any changes made to the composition by the lines of script between StartUndo() and EndUndo() are stored as a single Undo event.
Changes captured in the undo event can be undone from the GUI using CTRL-Z, or the Edit menu. They can also be undone from script, by calling the Undo function. keep determines whether the captured undo event is to kept or discarded. Specifying ‘true’ results in the undo event being added to the undo stack, and appearing in the appropriate menu. Specifying ‘false’ will result in no undo event being created. This should be used sparingly, as the user (or script) will have no way to undo the preceding commands.
If the script exits before the EndUndo() is called Fusion will automatically close the undo event.
composition:StartUndo(“Add some tools”)
bg1 = Background{}
pl1 = Plasma{}
mg1 = Merge{ Background = bg1, Foreground = pl1 }
composition:EndUndo(true)
Parameters:
keep (boolean) – keep
Execute()
Executes a script string for the composition. To execute a script in the context of fusion use fusion:Execute( ... ) instead.
ExpandZone()
Export()
Exports the current composition to a file.
FindTool()
Finds first tool by name
Parameters:
name (string) – name
Returns: Tool
Return type: Tool
FindToolByID()
Finds tools of a given type
Returns only the first found tool.
To find the next tool use the prev parameter to supply the previous tool.
-- Create three Blur tools
blur1 = Blur
blur2 = Blur
blur3 = Blur
print (comp:FindToolByID(“Blur”).Name)
-- Prints: Blur1
print (comp:FindToolByID(“Blur”, blur1).Name)
-- Prints: Blur2
print (comp:FindToolByID(“Blur”, blur2).Name)
-- Prints: Blur3
Parameters:
id (string) – id
prev (Tool) – prev
Returns: tool
Return type: Tool
GetCompPathMap()
Returns a table of all Composition path maps
build_ins If set build-in (read-only) PathMaps will be returned.
defaults If set the default PathMaps will be returned, else excluded.
-- Returns custom PathMaps
==comp:GetCompPathMap(false, false)
-- Show all, same as true, true
==comp:GetCompPathMap()
Parameters:
built_ins (boolean) – built_ins
defaults (boolean) – defaults
Returns: map
Return type: table
GetConsoleHistory()
This function is useful for getting all information displayed in the console between two points. Could be used to search for warnings or errors generated by previous scripts.
Returns a table with the history of the console between two points. If endSeq is omitted, the startSeq the console sequence number that the script will start reading from.
endSeq the console sequence number that the script will stop reading at.
Script gets all history starting from the variable passed into startSeq. If both values are omitted, returns a general table about the history of the console (number of lines, etc.) If no parameters are given the total number of lines will be returned in the Total key.
-- Get the total number of console lines
dump(composition:GetConsoleHistory().Total)
-- Get the console history lines 1 and 2
dump(composition:GetConsoleHistory(1, 2))
GetData([name])
Get custom persistent data
name name of the data. This name can be in “table.subtable” format, to allow persistent data to be stored within subtables.
Persistent data is a very useful way to store names, dates, filenames, notes, flags, or anything else, in such a way that they are permanently associated with this instance of the object, and are stored along with the object using SetData(), and can be retrieved at any time with GetData().
The method of storage varies by object: SetData() called on the Fusion app itself will save its data in the Fusion.prefs file, and will be available whenever that copy of Fusion is running. Calling SetData() on any object associated with a Composition will cause the data to be saved in the .comp file, or in any settings files that may be saved directly from that object. Some ephemeral objects that are not associated with any composition and are not otherwise saved in any way, may not have their data permanently stored at all, and the data will only persist as long as the object itself does.
Returns a value that has been fetched from the object’s persistent data. It can be of almost any type
tool = tool or comp.ActiveTool
tool:SetData(“Modified.Author”, fusion:GetEnv(“USERNAME”))
tool:SetData(“Modified.Date”, os.date())
author = tool:GetData(“Modified.Author”)
dt = tool:GetData(“Modified.Date”)
print(“Last modified by” ..author.. “ on ” ..dt)
Parameters:
name (string) – name
Returns: value
Return type: (number|string|boolean|table)
GetFrameList()
Retrieves a table of the comp’s ChildFrames.
ChildFrames are the windowed workspace of Fusion. This function allows the user to access each of the available ChildFrame window objects, and their views.
windowlist = composition:GetFrameList()
tool = comp.ActiveTool
for i, window in pairs(windowlist) do
window:ViewOn(tool, 1)
end
GetMarkers()
Returns a table of timeline markers.
GetNextKeyTime([time][, tool])
Returns the keyframe time of the next keyframe.
It can be used to either check for a keyframe among all tools in the composition, or for a specified tool only.
time The source time for the search.
tool If set keyframes only for the tool will be returned.
Parameters:
time (number) – time
tool (Tool) – tool
Returns: time
Return type: number
GetPrefs([prefname][, exclude-defaults])
Retrieves a table of comp-specific preferences, or a single value.
prefname The name of the specific preference to be retrieved. Use dots to indicate subtables. If no prefname or nil is specified, a table of all the preferences is returned.
exclude-defaults Do not include preferences with defaults if true
This function is useful for getting the full table of preferences for a Composition, or a subtable, or a specific value.
-- All preferences
dump(comp:GetPrefs())
-- A sepcific preference
dump(comp:GetPrefs(“Comp.AutoSave.Enabled”))
-- All but default preferences
dump(comp:GetPrefs(nil, false))
Parameters:
prefname (string) – prefname
exclude-defaults (boolean) – exclude-defaults
Returns: prefs
Return type: table
GetPrevKeyTime([time][, tool])
Returns the keyframe time of the previous keyframe.
It can be used to either check for a keyframe among all tools in the composition, or for a specified tool only.
time The source time for the search.
tool If set keyframes only for the tool will be returned.
Parameters:
time (number) – time
tool (Tool) – tool
Returns: time
Return type: number
GetPreviewList()
Retrieves a table of previews
The GetPreviewList function is used to determine what views are available for a flow or for Fusion. The object itself is a View object that can then be passed on to the various functions that affect views in Fusion.
Returns a table of all available views for a composition. For floating views use the fusion:GetPreviewList function instead.
Parameters:
include_globals (boolean) – include_globals
Returns: previews
Return type: table
GetRedoStack()
GetToolList()
Returns a table of all tools or selected tools.
selected If the selected argument is set to true then GetToolList returns a list of handles to the selected tools in the composition. If no tools are selected then the table returned is nil. If the selected argument is false, or empty then a table with handles to all tools in the composition are returned.
regid This string value will limit the return of the GetToolList function to tools of a specific type (this type is related to the TOOLS_RegID attribute).
-- outputs the name of every tool in the composition
dump(composition:GetToolList())
-- Get all selected tools
dump(composition:GetToolList(true))
-- Get all loaders
dump(comp:GetToolList(false, “Loader”))
Parameters:
selected (boolean) – selected
regid (string) – regid
Returns: tools
Return type: table
GetUndoStack()
GetViewList()
Returns all the view in the composition.
Heartbeat()
Heartbeat
IsLocked()
Returns true if popups and updates are disabled.
Use this function to see whether a composition is locked or not.
Returns a boolean with the locked status of the comp.
Returns: locked
Return type: boolean
IsPlaying()
Returns true if the comp is being played.
Returns: playing
Return type: boolean
IsReadOnly()
IsRendering()
Returns true if the comp is busy rendering.
It will return true if it is playing, rendering, or just rendering a tool after trying to view it.
This is equal to the state of COMPB_Rendering composition attribute.
Returns: rendering
Return type: boolean
IsViewShowing()
IsZoneExpanded()
Lock()
Lock the composition from updating
The Lock() function sets a composition to non-interactive (“batch”, or locked) mode. This makes Fusion suppress any dialog boxes which may appear, and additionally prevents any re-rendering in response to changes to the controls. A locked composition can be unlocked with the Unlock() function, which returns the composition to interactive mode.
It is often useful to surround a script with Lock() and Unlock(), especially when adding tools or modifying a composition. Doing this ensures Fusion won’t pop up a dialog to ask for user input, e.g. when adding a Loader, and can also speed up the operation of the script since no time will be spent rendering until the comp is unlocked.
comp:Lock()
-- Will not open the file dialog, since the composition is locked
my_loader = Loader()
comp:Unlock()
Loop(enable)
Enables looping interactive playback
This function is used to turn on the loop control in the playback controls of the composition.
Parameters:
enable (boolean) – enable
Note
This method is overloaded and has alternative parameters. See other definitions. Enables looping interactive playback.
Loop(mode)
Enables looping interactive playback.
This function is used to turn on the loop control in the playback controls of the composition.
Parameters:
mode (string) – mode
Note
This method is overloaded and has alternative parameters. See other definitions. Enables looping interactive playback.
MapPath(path)
Expands path mappings in a path string
Retruns a file or directory path with all path maps expanded into their literal path equivalents.
There are a number of default and user-specified path maps within Fusion that are intended to provide convenient ways to access common locations, or for flexibility in scripting. These can be any string, but often end in a colon, e.g. Fusion:, Comp:. They are expanded into a literal path as specified by the Path Maps preferences page.
However, many Fusion functions (and all Lua functions) require strictly literal paths. MapPath() can be used to easily convert any path map into a fully-expanded literal path. If there is no path map at the beginning of the path, MapPath() will just return the unchanged path.
In addition to expanding all global path maps like Fusion:MapPath(), Composition:MapPath() will also expand any path maps listed in the composition’s Path Map preferences, and the following built-in defaults.
For multiple directories use MapPathSegments().
Parameters:
path (string) – path
Returns: mapped
Return type: string
MapPathSegments()
Expands all path mappings in a multipath
MapPathSegments is similar to MapPath but works with strings that contain multiple directories. The return value is a table with all expanded paths while MapPath only expands the first segment and discards the rest.
dump(comp:MapPathSegments(“AllDocs:Settings;Fusion:Settings”))
-- Returns table: 0x03800440
-- 1 = C:\Users\Public\Documents\Blackmagic Design\Fusion\Settings
-- 2 = C:\Program Files\Blackmagic Design\Fusion 8\Settings
Parameters:
path (string) – path
Returns: mapped
Return type: table
NetRenderAbort()
NetRenderAbort
NetRenderEnd()
NetRenderEnd
NetRenderStart()
NetRenderStart
NetRenderTime()
NetRenderTime
Paste()
Paste tools from the Clipboard or a settings table.
settings if not supplied the Clipboard will be used.
Parameters:
settings (table) – settings
Returns: success
Return type: boolean
Play([reverse])
Starts interactive playback.
This function is used to turn on the play control in the playback controls of the composition.
reverse Play in reverse direction.
Parameters:
reverse (boolean) – reverse
Print()
Print in the context of the composition.
Useful to print to a console of a different composition.
Redo()
Redo one or more changes to the composition
The Redo function reverses the last undo event in Fusion. Note that the value of count can be negative, in which case Redo will behave as an Undo, acting exactly as the Undo() function does.
count specifies how many redo events to trigger.
Parameters:
count (number) – count
Render([wait][, start][, end][, proxy][, hiq][, motionblur])
Start a render
The Render function starts rendering the current composition. There are two forms for calling this function, one where the arguments are passed directly, and a second form where all the arguments are passed in a table. The table format is useful for declaring noncontiguos render ranges, such as the following one.
Returns true if the composition rendered successfully, nil if it failed to start or complete the render.
Note
This method is overloaded and has alternative parameters. See other definitions.
Arguments
wait_for_render a true or false value indicating whether the script should wait for the render to complete, or continue processing once the render has begun.
renderstart the frame to start rendering at.
renderend the frame to stop rendering at.
step render 1 out of x frames. For example, a value of 2 here would render every second frame.
proxy scale all frames down by this factor, for faster rendering.
hiQ do high-quality rendering (defaults to true, if not specified).
mblur calculate motion-blur when rendering (defaults to true, if not specified)
Reset()
ReverseMapPath()
Collapses a path into best-matching path map
RunScript()
Run a script
Save()
Save the composition
SaveAs()
Save the composition
SaveCopyAs()
Save a copy of the composition
SaveVersion()
Save the composition
SetActiveTool()
Set the currently active tool
SetData()
Set custom persistent data
SetMarker()
Creates or changes a timeline marker.
SetPrefs()
Set preferences from a table of attributes
SetReadOnly()
ShowView()
StartUndo()
Start an undo event
Stop()
Stops interactive playback
Undo()
Undo one or more changes to the composition
Unlock()
Unlock the composition
UpdateMode [Read-Write]
UpdateViews()
XPos [Read-Write]
YPos [Read-Write]
_Output_Error()
_Output_Print()
_Save()
_SaveAs()
Save the composition
_SaveCopyAs()
Save a copy of the composition
_SetCurrentTime()
Object:Comp()
Object:Composition()
Object:DoAction()
Object:GetData()
Get custom persistent data
Object:GetID()
Object:GetReg()
Object:QueueAction()
Object:SetData()
Set custom persistent data
Object:TriggerEvent()
.ClassName [read-only] :GetApp() :GetAttrs() :GetHelp() :GetHelpRaw() :SetAttrs() "