MM Developer's Guide
MM Interfaces | MM Methods | MM Types and Misc API

IMoaMmXSpriteActor

Interface ID: IID_IMoaMmXSpriteActor
Pointer type: PIMoaMmXSpriteActor
Inheritance: IMoaMmPropOwner
Header file: mmixasst.h

Description

The IMoaMmXSpriteActor interface lets an asset Xtra implement runtime behavior for presenting during playback of a multimedia piece. The methods of this interface enable asset Xtras to describe their capabilities to an application, to draw themselves, to handle events, and to interact with their asset and the application.

Methods

Scripting support

GetProp()
SetProp()
CallFunction()

Asset interaction

SetCallback()
Notify()

Event handling

GetCaps()
ContainsPoint()
Event()

Imaging

CollectChanges()
Image()

CallFunction()

Syntax

CallFunction(MoaMmSymbol methodName, MoaLong nArgs, ConstPMoaMmValue pArgs, PMoaMmValue pResult)

Parameters

methodName
Symbol of the method (function) to call
nArgs
Number of arguments, excluding reserved value in pArgs[0]
pArgs
Array of arguments, with the first valid argument at pArgs[1]
pResult
Pointer to a MoaMmValue to receive a result value, if any

Returns

kMoaErr_NoErr Function exists and operation was successful
kMoaErr_BadParam Invalid nArgs, pArgs, or pResult passed in
kMoaMmErr_FunctionNotFound Function not supported by this actor
kMoaErr_OutOfMem Couldn't allocate memory needed to execute function
kMoaMmErr_InternalError Function exists, args ok, can't execute internal error
kMoaMmErr_NoArgExpected Wrong number of args: 0 expected
kMoaMmErr_OneArgExpected Wrong number of args: 1 expected
kMoaMmErr_TwoArgsExpected Wrong number of args: 2 expected
kMoaMmErr_ThreeArgsExpected Wrong number of args: 3 expected
kMoaMmErr_FourArgsExpected Wrong number of args: 4 expected
kMoaMmErr_WrongNumberOfArgs Wrong number of arguments, non- specific
kMoaMmErr_IntegerExpected Type mismatch: integer value argument expected
kMoaMmErr_SymbolExpected Type mismatch: symbol value argument expected
kMoaMmErr_FloatExpected Type mismatch: float value argument expected
kMoaMmErr_StringExpected Type mismatch: string value argument expected
kMoaMmErr_PointExpected Type mismatch: point value argument expected
kMoaMmErr_RectExpected Type mismatch: rect value argument expected
kMoaMmErr_ValueTypeMismatch Type mismatch: other value argument expected
kMoaDrErr_CastMemberExpected Type mismatch: CMRef value argument expected (Director only)

Description

Calls a sprite actor scripting function. This method allows sprite actors to export arbitrary functions to be used in the host application's scripting or expression language. The caller passes the symbol of the function to call in the methodName parameter, along with the argument count (nArgs), the argument array (pArgs), and optionally, a pointer to a MoaMmValue to receive any result value. The argument array, pArgs, contains an array of MoaMmValues corresponding to the function arguments. pArgs[0] is a reserved value and should not be referenced. The function parameters are supplied in pArgs[1] through pArgs[nArgs]. These MoaMmValues are owned by the host application and should not be released by this method. If the method has a return value, it should populate pResult with a new MoaMmValue containing the result. If the Xtra does not support the function specified by methodName, it should return the error code kMoaMmErr_FunctionNotFound. If the number or types of arguments are incorrect, the function should return one of the appropriate MoaMmErrors (see mmtypes.h).

CollectChanges()

Syntax

CollectChanges(ConstPMoaMmXSpriteInfo pActorInfo, PIMoaMmChangeCollector pChangeCollector)

Parameters

pActorInfo
Pointer to an ActorInfo structure for context in which actor is imaged
pChangeCollector
Pointer to an IMoaMmChangeCollector interface

Returns

kMoaErr_NoErr Successful, change rects (if any) submitted
kMoaMmErr_NotImplemented Sprite is static, updates are requested using InvalSpriteRect(). You must set the kMoaMmXSpriteCapsFlags_IsStatic sprite caps flag in your GetCaps().

Description

Obtains change rectangles for the actor. This method is called for all actors that have not otherwise changed from the current frame to the next (sprite rectangle, ink mode, color, and so on. are the same). This gives the actor an opportunity to let the host application know of any changes occurring within the actor's bounding box, so that the actor can be called back to image those changes. Using the supplied IMoaMmChangeCollector interface, CollectChanges() can submit multiple change rectangles. For each rectangle, call pChangeCollector->lpVtbl->AddChangeRect() with the rectangle to submit. Submitting an empty rectangle has no effect. If there are no change rectangles, return kMoaErr_NoErr without calling pChangeCollector->lpVtbl->AddChangeRect(). To optimize compositing, you can call AddChangeRectAbove() instead of AddChangeRect(). This should be used only if the rectangle specified is completely opaque in your sprite; this tells the host application that it is not necessary to redraw the area directly behind the supplied rectangle. Even if the host application does not support this optimization, it still accepts AddChangeRectAbove(), in this case, AddChangeRectAbove() has the same effect as AddChangeRect().

ContainsPoint()

Syntax

ContainsPoint(ConstPMoaMmXSpriteInfo pActorInfo, ConstPMoaPoint pTestPoint, MoaBoolParam * pTestResult)

Parameters

pActorInfo
Pointer to MoaMmXSpriteInfo for context in which actor draw
pTestPoint
Pointer to the point to test
pTestResult
Pointer to MoaLong for result: 0 if not within, non-0 if within

Returns

kMoaErr_NoErr Successful, pTestResult set

Description

Queries the actor to determine if a given point lies within its visual region in the playback window. The actor should use the information in pActorInfo (sprite rectangle, ink mode, and so on) and the point supplied in pTestPoint, to perform the test. The result of the test should be returned in pTestResult: 0 if the point is not within the area occupied by the actor sprite; non-0 if it is. If the actor's shape is non-rectangular, the test should take this into account and not use the sprite rectangle. This is called by the host application when mouse hit-testing and rollover-testing is being performed.

Event()

Syntax

Event(ConstPMoaMmEventInfo pEventInfo, ConstPMoaMmPlayerStateInfo pPlayerStateInfo, MoaBoolParam * pHandled)

Parameters

pEventInfo
Pointer to a MoaMmEventInfo structure containing information about the event
pPlayerStateInfo
Pointer to a caller-owned structure containing various state information about the player
pHandled
Pointer to a MoaBoolParam to receive the handled status of the event

Returns

kMoaErr_NoErr Successful, event handled or intentionally passed
kMoaErr_OutOfMem Wanted event but couldn't handle due to memory error
kMoaMmErr_InternalError Wanted event but couldn't handle due to an internal error

Description


Notifies an actor that an event of interest has occurred. The actor subscribes to sets of events by setting the appropriate flags in the eventMask field of the MoaMmXSpriteCaps structure returned by its IMoaMmXSpriteActor::GetCaps() method.

Events fall into the following categories:


See the description of the MoaMmEventInfo type and associated constants later in this chapter for more details on these event types.

Each time the Event() method is called, the pEventInfo structure passed in contains the identity of the specific event type being sent. A number of events include additional information, including time and mouse position. These include mouseDown, mouseUp, mouseUpOut, mouseDblClick, rightMouseDown, rightMouseUp, rightMouseUpOut, rightMouseDblClick, keyDown, keyUp, idle, and step.

Note: in Director, the modify key fields of the event info structure are not updated for events received while the mouse button is down. To get the actual values of any modify keys, you'll need to use native OS calls.

The actor should set the value at pHandled to kMoaMmSprEvent_Handled if it handled the event, or kMoaMmSprEvent_Pass if it wants to pass the event along to other objects in the event hierarchy (such as sprite scripts in Director).

Important: In almost all cases, imaging should only occur in your Image() method. Only direct-to-screen actors, which need to image independently of the animation tempo (such as digital video or other time-based media) should image in response to events. In this case, only the idle event should be used. Offscreen imaging or imaging in response to any other events is not supported and may have unpredictable results.

The posting of idle events is application and CPU-dependent. Idle events are posted when the host application has free cycles; you are not guaranteed to get any idle events. Idle events should be used only to perform optional background tasks such as the servicing of time-based media. Time- based media should also be serviced when receiving Step events, which are guaranteed to occur once, and only once, per animation frame.

If you need data from the actor information in your Event() method (such as the sprite rectangle), save it in an instance variable from your last Image() method. If you need a graphic context during an Event()method call, (for example to image sprite direct-to-stage during idle events), save a native representation (for example, a WindowPtr) obtained from the graphic context in your Image() method. The WindowPtr/HWND may not be in existance for the entire life of an actor instance. Changing some window properties may cause a window to get destroyed and recreated. Starting with Director MX 2004 this is more likely to occur, as it happens when windows are docked/undocked in authoring, or when the display template properties associated with a window are changed.

The events should be used only to set internal state information. For example, rather than doing span initialization (that may require the actor information and a graphic context) in your SpanBegin code in an Event() method, set an internal state variable, then initialize it when your Image() method is called, so you'll have actor information and a graphic context available.

Pass back the value kMoaMmSprEvent_Handled as pHandled if the event is completely handled by your code and shouldn't be passed to the next event handler. Pass back kMoaMmSprEvent_Pass if the event should be passed to the next event handler.

GetCaps()

Syntax

GetCaps(PMoaMmXSpriteCaps pActorCaps)

Parameters

pActorCaps
Pointer to a MoaMmXSpriteCaps structure to receive actor capabilities

Returns

kMoaErr_NoErr Successful

Description

Obtains the sprite actor capabilities for this sprite actor. This method is called by the host application directly after the actor instance is created. As it plays, a sprite may update its capabilities by calling the IMoaMmSpriteCallback::InvalSpriteCaps() method; this forces the host to call the GetCaps() method again.

This method should populate all of the fields of the supplied MoaMmXSpriteCaps structure: the eventMask, flags, requiredImageMode, and preferredImageMode. The following tables describe these fields. For more information, see mmtypes.h for the event masks, flags, and image modes.

The eventMask indicates what classes of events the actor wishes to receive (such as mouse events, keyboard events, and so on.)
The flags field indicates whether the actor supports various capabilities, such as auto-tab keyboard focus handling and persistency across sprite spans.

GetProp()

Syntax

GetProp(MoaMmSymbol symbol, PMoaMmValue pPropValue)

Parameters

symbol
MoaMmSymbol representing the requested property
pPropValue
Pointer to a MoaMmValue to receive the value

Returns

kMoaErr_NoErr Property exists and value was returned
kMoaErr_BadParam Invalid pPropValue passed in
kMoaMmErr_PropertyNotFound Property isn't supported by this actor
kMoaMmErr_InternalError Property exists but couldn't get due to internal error
kMoaMmErr_NoMemForString Couldn't allocate memory for string value data
kMoaErr_OutOfMem Couldn't allocate memory for other value data

Description

Gets the value of a sprite actor property. The host application passes in the symbol for the requested property; this is an abstract reference to a string in the host application's symbol dictionary. Use IMoaMmUtils::StringToSymbol() to get the MoaMmSymbol for any string, and IMoaMmUtils::SymbolToString() to convert any symbol to a string. This method should populate pPropValue with a new value; the host application then assumes ownership of the value and is responsible for releasing it. This method returns the error code kMoaMmErr_PropertyNotFound if it does not support the specified property symbol.

Image()

Syntax

Image(ConstPMoaMmXSpriteInfo pActorInfo, ConstPMoaMmPlayerStateInfo pPlayerStateInfo, PIMoaMmGC pGC)

Parameters

pActorInfo
Pointer to MoaMmXSpriteInfo structure for context in which actor is drawn
pPlayerStateInfo
Pointer to a caller-owned CMoaMmPlayerStateInfo structure containing state information about the player
pGC
Pointer to an IMoaMmGC interface for the graphics context into which the sprite actor should be imaged

Returns

kMoaErr_NoErr Successful, sprite imaged into supplied GC
kMoaMmErr_NotImplemented Actor doesn't have a visual representation
kMoaMmErr_GCTypeNotSupported Doesn't support supplied GC type
kMoaErr_OutOfMem Couldn't image due to memory error
kMoaMmErr_InternalError Couldn't image due to an internal error

Description


Images your sprite actor. pActorInfo contains a pointer to a MoaMmXSpriteInfo structure which describes the context in which your actor is to be imaged. This includes information such as the ink mode, sprite rectangle in which to draw, and other imaging parameters. pPlayerStateInfo contains global information about the player's state: whether it's playing or stopped, and whether sound playback is enabled. pGC contains a PIMoaMmGC, a pointer to a graphics context interface describing the native window or offscreen buffer into which the sprite should be drawn.

If you support the direct-to-screen imaging mode, the graphics context supplied can be associated with an operating system window on the playback machine. If the actor is offscreen-only, the graphics context will always be associated with an offscreen buffer.

Windows note: before your actor begins imaging, you must explicitly set the raster drawing mode of the device using the Windows SetROP2() function.

If your actor has no visual component, just return kMoaErr_NoErr.

Notify()

Syntax

Notify(MoaLong msgCode, PMoaVoid refCon)

Parameters

msgCode
MoaLong
refCon
PMoaVoid

Returns

kMoaErr_NoErr Successful
kMoaMmErr_UnknownNotifyMsgCode Notify message code not supported Used for communicating between assets and their actors. The NotifySprites() method of the IMoaMmAssetCallback interface calls this method for all active sprite actors.

Description


Used for communicating between assets and their actors. The NotifySprites() method of the IMoaMmAssetCallback interface calls this method for all active sprite actors.

Note: Xtra developers may specify values in the range of 0 to 65535 for their notification codes. Higher values are reserved by Adobe for future use.

SetCallback()

Syntax

SetCallback(PIMoaMmSpriteCallbackpSpriteCallback)

Parameters

pSpriteCallback
Pointer to an instance of the IMoaMmSpriteCallback interface

Returns

kMoaErr_NoErr Interface set
kMoaMmErr_NotImplemented Callback interface not used

Description


Receives an IMoaMmSpriteCallback interface containing callback methods for the sprite. In Director, this class also supports the IMoaDrSpriteCallback interface containing Director-specific callbacks. This is called directly after the host application calls an asset's NewXActor() method.

Important: If you want to hold on to the callback interface, you must call AddRef() on the interface and store it in an instance variable, then release it in the MoaDestroy function of your actor class.

SetProp()

Syntax

SetProp(MoaMmSymbol symbol, ConstPMoaMmValue pPropValue)

Parameters

symbol
MoaMmSymbol representing the property to set
pPropValue
Pointer to a ConstPMoaMmValue which contains the value

Returns

kMoaErr_NoErr Property exists and value was set
kMoaErr_BadParam Invalid pPropValue passed in
kMoaMmErr_PropertyNotFound Property isn't supported by this class
kMoaMmErr_InternalError Property exists, value ok, can't set due to internal error
kMoaMmErr_NoMemForString Can't allocate memory for setting string value data
kMoaErr_OutOfMem Can't allocate memory for setting other value data
kMoaMmErr_IntegerExpected Type mismatch: integer value expected
kMoaMmErr_SymbolExpected Type mismatch: symbol value expected
kMoaMmErr_FloatExpected Type mismatch: float value expected
kMoaMmErr_StringExpected Type mismatch: string value expected
kMoaMmErr_PointExpected Type mismatch: point value expected
kMoaMmErr_RectExpected Type mismatch: rect value expected
kMoaMmErr_ValueTypeMismatch Type mismatch: other value expected (non-specific)
kMoaDrErr_CastMemberExpected Type mismatch: CMRef expected (Director only)

Description


Sets the value of a sprite actor property. The host application passes in the symbol for the property to set. This is an abstract reference to a string in the host application's symbol dictionary. Use IMoaMmUtils::StringToSymbol() to get the MoaMmSymbol for any string, and IMoaMmUtils::SymbolToString() to convert any symbol to a string. This method should take the value supplied in pPropValue and use it to update the object's internal representation of the property. The host application continues to maintain ownership of the MoaMmValue. This method should not release the passed-in value. SetProp() should return the error code kMoaMmErr_PropertyNotFound if it does not support the specified property symbol.

Copyright © 1995-2008 Adobe Macromedia Software LLC, Inc.