Avid Motion Graphics 2.5 User guide

Brand: Avid

Model: Motion Graphics 2.5

Category: Software

Type: User guide

Avid Motion Graphics 2.5 is a powerful tool that allows you to create and edit stunning motion graphics and visual effects. With its intuitive interface and wide range of features, Motion Graphics 2.5 is perfect for both beginners and experienced users.

Some of the key features of Motion Graphics 2.5 include:

A variety of tools for creating and editing motion graphics, including vector drawing, text animation, and 3D modeling.
A powerful rendering engine that can create high-quality output for both video and film.
A wide range of effects and filters that can be used to enhance your motion graphics.

Some of the key features of Motion Graphics 2.5 include:

A variety of tools for creating and editing motion graphics, including vector drawing, text animation, and 3D modeling.
A powerful rendering engine that can create high-quality output for both video and film.
A wide range of effects and filters that can be used to enhance your motion graphics.



Avid Motion Graphics™

Application Programming Interface (API) Guide

Version 2.5

Date Revised

Changes Made

04 February 2013 Added version and changes date.

28 November 2012

Reviewed original preliminary document, and updated and removed

unnecessary sections.

Persons to Contact Regarding this Document

 William Hadsell, Principle Product Manager

William.Hadsell@avid.com

 Danielle Prigmore, Third-Party Program Manager

75 Network Drive, Burlington, Massachusetts 01803

(978) 640-3210

Danielle.Prigmore@avid.com

Legal Notices

Product specifications are subject to change without notice and do not represent a commitment on the part of Avid Technology, Inc.

The software described in this document is furnished under a license agreement. You can obtain a copy of that license by visiting Avid's Web site at

www.avid.com. The terms of that license are also available in the product in the same directory as the software. The software may not be reverse

assembled and may be used or copied only in accordance with the terms of the license agreement. It is against the law to copy the software on any

medium except as specifically allowed in the license agreement.

No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and

recording, for any purpose without the express written permission of Avid Technology, Inc.

Attn. Government User(s). Restricted Rights Legend

U.S. GOVERNMENT RESTRICTED RIGHTS. This Software and its documentation are “commercial computer software” or “commercial computer

software documentation.” In the event that such Software or documentation is acquired by or on behalf of a unit or agency of the U.S. Government, all

rights with respect to this Software and documentation are subject to the terms of the License Agreement, pursuant to FAR §12.212(a) and/or DFARS

§227.7202-1(a), as applicable.

Trademarks

Adrenaline, AirSpeed, ALEX, Alienbrain, Archive, Archive II, Assistant Avid, Avid Unity, Avid Unity ISIS, Avid VideoRAID, CaptureManager,

CountDown, Deko, DekoCast, FastBreak, Flexevent, FXDeko, iNEWS, iNEWS Assign, iNEWS ControlAir, Instinct, IntelliRender, Intelli-Sat, Intelli-sat

Broadcasting Recording Manager, Interplay, ISIS, IsoSync, LaunchPad, LeaderPlus, ListSync, MachineControl, make manage move | media, Media

Composer, NewsCutter, NewsView, OMF, OMF Interchange, Open Media Framework, Open Media Management, SIDON, SimulPlay, SimulRecord,

SPACE, SPACEShift, Sundance Digital, Sundance, Symphony, Thunder, Titansync, Titan, UnityRAID, Video the Web Way, VideoRAID, VideoSPACE,

VideoSpin, and Xdeck are either registered trademarks or trademarks of Avid Technology, Inc. in the United States and/or other countries.

All other trademarks contained herein are the property of their respective owners.

Avid Motion Graphics API Guide v2.5 • 9329-65253-00 Rev. A • 4 February 2013

This document contains confidential and proprietary information. Usage and dissemination of this information is governed by the applicable non-

disclosure agreements This document is distributed by Avid in online (electronic) form only, and is not available for purchase in printed form.

Contents

Persons to Contact Regarding this Document ........................................................................................................... 1

Legal Notices ............................................................................................................................................................. 2

Copyright and Disclaimer ...................................................................................................................................... 2

Overview ................................................................................................................................................................... 4

Naming Conventions ................................................................................................................................................. 4

Data Integration - Application Programming Interface (API) ................................................................................... 4

Technical Support Information ................................................................................................................................ 14

Accessing Online Support ................................................................................................................................... 14

Overview

The Avid Motion Graphics Application Programming Interface (API) is comprised of

very few routines due to the Avid Motion Graphics list and editors design. In theory, only

two commands (itemset() and itemget()) should be needed to set or retrieve any

parameter of the program. But in practice, a few more are implemented for your

convenience.

Avid Motion Graphics provides 3

party interaction through the following API:

• Data Integration API which allows 3

party connectivity with the AMG

Rendering Engine.

Naming Conventions

The following naming conventions are used in this document.

listName : stands for the name of a Avid Motion Graphics List.

itemName : stands for the name of an element of a Avid Motion Graphics List.

editorName : stands for the name of an editor of a list.

value : stands for a value assigned or retrieved of an editor.

editorIndex : stands for the component index of the editor.

editorName[editorIndex] accesses the editorIndex component of an editor, for example,

for a vector editor, editor[0] would access the 'x' component, editor[1] the 'y' component,

etc.

A -1 in editorIndex means the whole editor.

Data Integration - Application Programming Interface (API)

Application Programming Interface (API) commands can be run from the scripting

language, such as Python or directly from a compiled module, without Python being

involved.

The following sections illustrate the commands available in both options.

PYTHON API

The following routines can be used from Python to interact with Avid Motion Graphics.

Note that the API routines receive strings as the names

for listName, itemName and editorName, while the value type depends on the editor being set

or queried, for example it can be a number, string, tupple, etc.

itemset

itemset(itemName, editorName, value, editorName, value, ...)

Sets the value of editors for itemName.

itemget

value = itemget(itemName, editorName)

Gets the value of an editor for itemName

itemgo

itemgo(itemName, editorName, value, transition, delay)

Performs like an itemset() but with an extra delay and transition parameters.

The delay value postpones the execution of the command the given time in seconds

The transition time means to apply the value by smootly interpolating from the previous value to

the new value in transition seconds.

Note that interpolating values does not make sense for all editors.

For example interpolating between strings, toggles, or pressing buttons.

Nevertheless some of these 'nonsense' transitions are implemented internally as special cases and

do really have a meaning. These cases are:

Changing the CULL flag of an object with transition will smoothly dissolve the object.

(Editors: OBJ_CULL_ON,OBJ_CULL_OFF, OBJ_CULL_INV, OBJ_CULL_TOG).

Changing the string assigned to a text with transition will smoothly dissolve between the

previous and the next string. (EditorTEXT_STRING).

Changing the matrix or quaternion with transition will internally interpolate by using quaterions.

(Editors OBJ_MATRIX,OBJ_QUAT).

itemkeys

itemkey(item, EDITOR, 'curveKey', [transition], [delay], [’curve1D[yourTransitionCurve’])

A command to animate values through curves. Sets a value, not a fixed value but a varying value

that changes in time according to the shape of the given curve. If the curve is in loop mode it

could be varying for ever. It can be a curve1D for single values or a curve3D for three

component values.

We also allow for a transition and delay in this command though they can be confusing because

the duration of the evolution is not the transition time as in the itemgo() but the one provided by

the curve. The meaning given to the transition time is the one it takes for the CURRENT

VALUE to adapt to the curve (that is also simultaneously varying). Thus the transition value is

usually just zero or a small percent of the time length of the curve. The time length of a curve1D

is given by itself (CURVE1D_TMIN and CURVE1D_TMAX). The time length of a curve3D is

given by the curve1D that the curve3D selects (or 1 if nothing is selected). The confussion comes

when mixing the two times length involved: transition and curve time length.

itemkey() also allows for an extra parameter after the delay which has to be a curve1D and

specifies the shape of the transition.

The time interval in the curve1D is irrelevant because its whole time interval [tmin, tmax] is

accessed in any case for the transition time.

itemnew

newItem = itemnew(listName, itemName, editorName, value, editorName, value, ...)

Creates a new element in listName named itemName with values assigned to editors

Note: In theory itemnew() should not be needed because you can create a new element of a list

with an itemset, for example:

itemset(itemName, "OBJ_NEW")

and then call:

itemset(itemName, editorName, value)

for every editor parameter we want to set.

But using itemnew() is a better way because:

- It provides a way to specify the name of the element (itemName)

Note that itemName already exists it is overwritten.

Note that if itemName is "" a new non exisiting name is assigned.

- All internal callbacks associated to every independent itemset that

should be needed are avoided because the whole element is initializated

after reading the whole itemnew().

itemdup

newItem = itemdup(listName, itemName)

Duplicates the element itemName of list listName.

Note that it duplicates all the reference chain generated from itemName.

itemgetParent

parentItem = itemgetParent(listName, itemName)

Returns the parent item of itemName.

itemgetChildren

childrenItem = itemgetChildren(listName, itemName)

Returns the list of children of itemName as a python tupple.

itemsetChildren

itemsetChildren(listName, itemName, listOfChildren)

Sets the list of children of itemName to the python tupple listOfChildren.

itemtree()

itemtree(listName, itemName, itemChild1, itemChild2, ...)

Sets the list of children of itemName to itemChild1, itemChild2, etc.

This routine performs the same action as itemsetChildren() but with another

syntax.

itemgetRefsTo

itemgetRefsTo(listName, itemName)

Returns the as a python tupple the list of references to itemName.

itemgetRefsFrom

itemgetRefsFrom(listName, itemName)

Returns the as a python tupple the list of references from itemName.

itemgetRefSetFrom

itemgetRefSetFrom(listName, itemName)

Returns the as a python tupple the recursive list of references from itemName.

ritemset, ritemget, ritemgo, ritemkey

ritemset(machineName, itemName, editorName, value, editorName, value, ...)

value = ritemget(machineName, itemName, editorName)

ritemgo(machineName, itemName, editorName, value, delay, transition)

ritemkey(machineName, item, EDITOR, 'curveKey', [transition], [delay],

[’curve1D[yourTransitionCurve]’])

Perform like an itemset(), itemget(), itemgo() or itemkey but on a remote machine.

machineName stands for the name of a machine in the network.

call

call(filename)

Directs python to read the given file.

cdcall

cdcall(filename)

Performs as a call(filename) but first changes the current working directory to the one of

filename.

uutmpfile()

filename = uutmpfile(string)

Creates a temporal file containing the uuencoded string.

This command is used internally to embed binary files into python syntax files.

C API

Most of the PYTHON API is available through the C API.

Using C code instead of Python scripts improves substantially the code performance because no

language interpreting is involved in the process.

The header file editem.h contains the declaration of the API routines.

The header file vtipos.h contains declaration of types.

cbell pointers versus string names:

The Python API routines were taking strings as the names for listName, itemName and

editorName, while the values were python types depending on the editor being set or queried.

Now listName, itemName and editorName are still string parameters but value is a pointer to a C

type depending on the editor being set or queried.

But using strings as parameters in routines called in real time is not a good idea because every

time the routine is called the pointer to the element has to be found out by searching through the

whole list. That is why we provide another set of routines that allow to specify directly the

pointer to the elements instead of their names. The pointer is initialized at the beginning and used

leater for every call to the routine.

Those pointer parameters are named as itemBell and editorBell in the headers and their type is

named cbell.

Base pointers in C plugins creating ipf lists.

When a C Plugin creates his own ipf lists it specifies the structure of data that contains the

parameters of a single item.

The pointer to such structure is called a base pointer. The plugin uses base pointers to access his

list item data.

Base pointers do not coincide with cbell pointers, there is an offset between them and a base

pointer can not be used where cbell pointers are expected. Routines are provided to convert

between them.

editemNew, editemSet, editemGet

const char* editemNew(const char * listName, const char * itemName,...);

void editemSet(const char * itemName, ...);

void * editemGet(const char * itemName, const char * editorName);

correspond to itemnew(), itemset(), itemget() from python.

editemSetBell, editemGetBell

void editemSetBell(cbell * itemBell, ...);

void * editemGetBell(cbell * itemBell, cbell * editorBell, int index=-1);

correspond to editemSet(), editemGet() but taking cbell pointers instead of

strings for itemName and editorName

editemGoBell

void editemGoBell(cbell * itemBell, cbell * editorBell,

void * ptr, int index, float transition, float delay);

ptr is the pointer to the value. (NULL for editors of type Button)

index is the index of the editor to set. (-1 for non indexed editors)

corresponds to an itemgo() from python.

editemToBell

cbell * editemToBell(const char * listName, const char * itemName);

cbell * bell = editemToBell(listName, itemName);

Returns the cbell pointer to an item of a list.

The pointer can be used later for the API routines expecting cbell pointers.

editemGetBase

void * editemGetBase(const char * listName, const char * itemName);

Return the Base pointer for an element of a plugin generated list.

editemGetBellName

const char * editemGetBellName(void * bell);

Returns the name of an item of a list given its cbell pointer.

editemGetItemName

const char * editemGetItemName(const char * listName, void * basePtr);

Returns the name of an item of a plugin generated list given the name of

the list and the Base pointer of the item.

editemGetListLength

int editemGetListLength(const char * listName);

Returns the number of elements in a list.

editemGetNumName

const char * editemGetNumName(const char * listName, int num);

Returns the name of the num indexed list element.

Together with editemGetListLength() allows to iterate through a list.

Accessing elements of editors of list type.

The type of variables pointed by pointers returned by the editemGet() routines depend on the

editor being queried. For example, we know that the editor 'IPFMODE_AXIS' in the list of

modes edits a boolean value, thus we can cast the pointer to that type:

void * ptr = editemget('ipfmode', 'IPFMODE_GRAPHICS_SIZE') int value = * (int *)

ptr;

and this is truth for all basic C types and those editor types included in the header file vtipos.h.

But some editors edit variable types that are declared and are not visible from the plugins.

This is specially problematic for editors editing a list of elements instead of a single one, for

example a list of strings, vectors, etc.

Thus, even if the pointer to the variable can be get through the editemget() routine nothing can

done with it because there is no header specifying the type.

We do not provide those headers because they change very often and should easily create

incompatibilities between versions. Instead, we provide routines that allow to access the

elements of the list:

editemGetEditorListLength

int editemGetEditorListLength(cbell * editorBell, void * ptr);

Returns the number of elements in a value ptr of list type.

editemGetEditorListData

void * editemGetEditorListData (cbell * editorBell, void * ptr, int index);

Returns the element index in a value of list type.

editemSetEditorListData

void editemSetEditorListData (cbell * bell, cbell * editorBell, void ** ptr, int len);

Performs an itemset() over a editor of type list.

editemSetEditorListDataIndex

void editemSetEditorListDataIndex(cbell * bell, cbell * editorBell, void * ptr, int index);

Performs an itemset() over a component of an editor of type list.

editemEditorListDataNew

void * editemEditorListDataNew(const char * typeName, int nComp);

Creates a new variable of type list.

editemEditorListDataDelete

void editemEditorListDataDelete(const char * typeName, void * ptr);

Deletes a variable created by using editemEditorListDataNew.

The following Auxiliar routines are provided:

-------------------------------------------------------

void * editemMalloc(int size);

void editemFree(void * data);

Perform a malloc and free of memory.

-------------------------------------------------------

int editemGetFrameCount();

Returns the current frame count.

-------------------------------------------------------

double editemGetTime();

Returns the current time counter in seconds.

-------------------------------------------------------

void editemCreateContextVideoSync();

unsigned int editemWaitContextVideoSync();

unsigned int editemGetContextVideoSync();

int editemContextGetField();

Allow to create a new rendering context for the current thread, and wait or query for video syncs.

-------------------------------------------------------

void editemDeleteThread(int thread, int signal);

int editemCreateThread(void * fun, void * arg);

Creates and deletes threads.

-------------------------------------------------------

CAUTION:

When sending parameters to routines with variable number of arguments like editemNew(),

editemSet(), editemGet(), care has to be taken to send exactly the types and number that are

expected or the program will easily crash or corrupt memory. The following examples illustrate

common mistakes:

Do not forget to append the NULL paremeter at the end:

This is a common mistake because in the Python syntax it is not needed.

Wrong:

editemNew("mat", "", "MAT_COLOR", v4(0.0992528, 0.0848328, 1.0, 1.0))

Right:

editemNew("mat", "", "MAT_COLOR", v4(0.0992528, 0.0848328, 1.0, 1.0), NULL);

Do not send other types than the expected. This is specially tricky for the family of integer and

float structures (float2, integer2, float3, etc.). In Python syntax we always send vector()

structures but in C they have to be correctly formed as integer or float structures. The

only way you have to know if an editor accepts an integer or float structure is to look at its list

in the interface and check what kind of values accepts.

Asuming i3(x,y,z) constructs an integer3 and v3(x,y,z) constructs a float3

Wrong:

editemNew("prim", "", "PRIM_CYL_RESXYZ", v3(11, 1, 1), NULL);

Right:

editemNew("prim", "", "PRIM_CYL_RESXYZ", i3(11, 1, 1), NULL);

Do not send float or integer type when double is expected. This is also very tricky. Routines with

variable number of arguments in C will only work with double values, so do not send integer or

float:

Wrong: (this sends an integer)

editemNew("prim", "", "PRIM_CYL_RADIUS_END" , 0, NULL);

Also Wrong: (this sends a float)

editemNew("prim", "", "PRIM_CYL_RADIUS_END" , 0.0f, NULL);

Right: (this really sends a double)

editemNew("prim", "", "PRIM_CYL_RADIUS_END" , 0.0, NULL);

Technical Support Information

Most products feature a number of coverage options. Avid Assurance service offerings are designed to

facilitate your use of Avid solutions. Service options include extended telephone coverage, automatic

software maintenance, extended hardware warranty, and preferred pricing on replacement parts. Offerings

and options may vary by product and are not available for all products.

For more information regarding Avid’s service offerings, visit

www.avid.com/support or call Avid Sales at

800-949-AVID (800-949-2843).

Program availability and details might vary depending on geographic location and are subject to change

without notice. Contact your local Avid office or your local Avid Reseller for complete program

information and pricing. However, if you need help locating an Avid office or Avid Reseller near you,

please visit

www.avid.com or call in North America 800-949-AVID (800-949-2843). International users

call 978-275-2480.

Accessing Online Support

Avid Online Support is available 24 hours per day, 7 days per week. Search the Knowledge Base to find

answers, to view error messages, to access troubleshooting tips, to download updates, and to read/join

online message-board discussions.

To access Avid Online Support:

 Go to www.avid.com/onlineSupport.

Note: Supplemental documentation for this release, if available, is provided on the Knowledge Base.

For the latest up-to-date information, browse the Knowledge Base at Avid Online Support.

Avid Motion Graphics 2.5 User guide

Brand: Avid

Model: Motion Graphics 2.5

Category: Software

Type: User guide

Some of the key features of Motion Graphics 2.5 include:

A variety of tools for creating and editing motion graphics, including vector drawing, text animation, and 3D modeling.
A powerful rendering engine that can create high-quality output for both video and film.
A wide range of effects and filters that can be used to enhance your motion graphics.

Download PDF

report

Avid Motion Graphics 2.5 User guide

Avid Motion Graphics 2.5 User guide

Related papers

Other documents