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


IMoaMmXAsset


Interface ID: IID_IMoaMmXAsset
Pointer type: PIMoaMmXAsset
Inheritance: IMoaMmPropOwner
Header file: mmixasst.h

Description


Use this Xtra interface to represent a particular type of media asset in a multimedia presentation. IMoaMmXAsset is an application-independent MOA Xtra interface. Because it inherits from the IMoaMmPropOwner interface, it includes methods for accessing various properties of the media represented by a particular implementation.

This interface is closely associated with the IMoaMmXSpriteActor and IMoaMmXTransition Xtra interfaces. For each media asset in a multimedia piece, there may be several presentations of that asset. Thus, an IMoaMmXAsset provider represents the asset itself, and an IMoaMmSpriteActor provider represents each distinct presentation of the asset.

For asset Xtras to work correctly on both Macintosh and Windows, you must handle byte-swapping in your streaming code. The processors supporting thes systems use different byte ordering of ints, longs, and other multibyte data types. Unless you manage byte-swapping, movies (including your Xtras that are saved on one platform and played on another) will produce unpredictable results.

Methods

Scripting support

GetProp()
SetProp()
CallFunction()
GetInMemPropsSize()
FinishPropsEditor()

Intialization

SetCallback()

Actor Management

Notify()
NewXActor()

Data Management

GetDefaultRect()
StreamOutMedia()
StreamInMedia()
FreeMedia()
GetInMemMediaSize()
GetStreamOutMediaSize()
StreamOutProps()
StreamInProps()
FreeProps()
GetStreamOutPropsSize()

Initalization

PrepareNewContent()

Authoring support

InvokeMediaEditor()
InvokePropsEditor()
InvokeAboutBox()
ImageStaticThumb()
BeginImageAnimThumb()
ServiceImageAnimThumb()
EndImageAnimThumb()

BeginImageAnimThumb()

Syntax

BeginImageAnimThumb(PIMoaMmXAssetThis,
PIMoaMmGCpGC,
ConstPMoaRectpImageRect)

Parameters

This
Pointer to the IMoaMmXAsset interface

pGC
PIMoaMmGCPointer to IMoaMmGC interface for graphics context in which to draw

pImageRect
ConstPMoaRectPointer to MoaRect specifying location and size of thumbnail

Returns

kMoaErr_NoErr Successful, ready to begin anim thumb drawing
kMoaMmErr_NotImplementedClass doesn't have an anim thumb
kMoaMmErr_GCTypeNotSupported Doesn't support supplied graphics context
kMoaErr_OutOfMem Couldn't prepare due to memory error
kMoaMmErr_InternalError Couldn't prepare due to internal error

Description


Implement this method to prepare to draw an animated thumbnail into the specified rectangle in the specified graphics context. BeginImageAnimThumb() does not actually draw anything into this rectangle; it merely signals the asset that the thumbnail imaging sequence is about to start. Imaging should occur in the IMoaMmXAsset::ServiceImageAnimThumb() method. When animation is to cease, the host application should call EndImageAnimThumb(). BeginImageAnimThumb() gets called by the host application only if the kMoaMmAssetCaps_CanImageAnimThumb flag is set in the asset capabilities stored in the registry. The supplied graphics context interface is owned by the caller and should not be released by this method.

Director 5.0 requires the ability to image animated thumbmails to screen graphics contexts; no caching is attempted for animated thumbmails. Therefore, it is not important that you support offscreen drawing for animated thumbnails; you need only support static thumbnails. Regardless of how you support thumbnails, you can claim to support both static and animated thumbmail drawing, then return kMoaMmErr_GCTypeNotSupported when called to draw if you find that you can't draw into the supplied GC.

If your Xtra requires that media data be loaded in order to image the animated thumbnails, set the kMoaMmAssetCaps_AnimThumbNeedsMedia asset capabilities flag in your registry entry.

When drawing in the native environment, be careful not to change any native drawing context settings, such as brush or pen type, colors, clip regions, and so on. Drawing outside of the supplied rectangle is not supported and may have unpredictable results.

CallFunction()

Syntax

CallFunction(PIMoaMmXAssetThis,
MoaMmSymbolmethodName,
MoaLongnArgs,
ConstPMoaMmValuepArgs,
PMoaMmValuepResult)

Parameters

This
Pointer to the IMoaMmXAsset interface

methodName
MoaMmSymbolSymbol representing the scripting function to call.

nArgs
MoaLongNumber of arguments, excluding the reserved value in pArgs[0]

pArgs
ConstPMoaMmValuePointer to an argument array, with the first valid argument at pArgs[1]

pResult
PMoaMmValuePointer to a MoaMmValue instance to receive a result value, if any

Returns

kMoaErr_NoErr Function exists, operation successful
kMoaErr_BadParam Invalid nArgs, pArgs, or pResult
kMoaMmErr_FunctionNotFound Function not supported by this class
kMoaErr_OutOfMem Couldn't allocate memory to execute function
kMoaMmErr_InternalError Function exists, arguments ok, but couldn't execute
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: (non-specific)
kMoaDrErr_CastMemberExpected Director only. Type mismatch: CMRef expected

Description


Implement this method to provide asset scripting. This method is invoked by the host application to call an asset function. This method allows assets to export arbitrary functions to use 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 real function parameters are supplied in pArgs[1] through pArgs[nArgs]. These MoaMmValuesare owned by the caller 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 returns the error code kMoaMmErr_FunctionNotFound. If the number or types of the arguments are incorrect, the function returns an appropriate MoaMmError (see mmtypes.h).


EndImageAnimThumb()

Syntax

EndImageAnimThumb(PIMoaMmXAssetThis,
PIMoaMmGCpGC,
ConstPMoaRectpImageRect)

Parameters

This
Pointer to the IMoaMmXAsset interface

pGC
PIMoaMmGCPointer to the IMoaMmGC interface for graphics context in which to draw

pImageRect
ConstPMoaRectPointer to a MoaRect specifying location and size of thumbnail

Returns

kMoaErr_NoErr Successful, animation thumbnail sequence ended
kMoaMmErr_NotImplemented Asset doesn't have animated thumbnail

Description


Implement this method to finish the thumbnail animation sequence. This call does not draw into the graphics context; it merely signals the end of the thumbnail animation sequence. The host application, not the asset, is responsible for erasing the thumbnail image area, if necessary. No erasing should be done by the asset.


FinishPropsEditor()

Syntax

FinishPropsEditor(PIMoaMmXAssetThis,
MoaBoolParamcommitChanges,
PMoaMmModifyFlagspModifyFlags)

Parameters

This
Pointer to the IMoaMmXAsset interface

commitChanges
MoaBoolParamValue reflecting whether user accepted or canceled modifications to properties

pModifyFlags
PMoaMmModifyFlagsFlag representing property modification state of the Xtra

Returns

kMoaErr_NoErr Editing complete, changes committed (if appropriate)
kMoaMmErr_NotImplemented Asset doesn't have a property editor
kMoaErr_OutOfMem Couldn't commit due to memory error
kMoaMmErr_InternalError Couldn't commit due to an internal error

Description


This method is called after the asset's InvokePropsEditor() method has returned to complete any changes made through that method. This method informs the media asset that the host application properties editor has been closed by the user. The parameter commitChanges reflects whether the user accepted or canceled modifications to the Xtra's properties. If accepted, the Xtra can finalize changes to its properties; if canceled, the Xtra retains the properties in effect before InvokePropsEditor() was called.

The following flags are valid for pModifyFlags:

Value Description
kMoaMmModifyFlags_None No media or properties have changed
kMoaMmModifyFlags_Media Media data has been modified
kMoaMmModifyFlags_Props Properties data has been modified

FreeMedia()

Syntax

FreeMedia(PIMoaMmXAssetThis)

Parameters

This
Pointer to the IMoaMmXAsset interface

Returns

kMoaErr_NoErr Media freed from memory (or no media to free)
kMoaMmErr_FreeFailed Media not freed. Host assumes media still in memory.

Description


Implement this method to release any memory in use by your asset for its media data. Typically, this method is called when the host application needs to purge an asset from memory. After this call, the host application assumes that the media data is no longer loaded; it calls IMoaMmXAsset::StreamInMedia()again if the media is needed). Return kMoaMmErr_FreeFailed if you failed to free your media data. Typically you should never return an error when freeing data, unless it's in use by another thread.


FreeProps()

Syntax

FreeProps(PIMoaMmXAssetThis)

Parameters

This
Pointer to the IMoaMmXAsset interface

Returns

kMoaErr_NoErr Properties freed from memory (or no props to free)
kMoaMmErr_FreeFailed Properties not freed. Host assumes still in memory.

Description


Implement this method to release any memory in use by your asset for its property data. Typically, this method is called when the host application needs to purge an asset from memory. After this call, the host application assumes that your property data is no longer loaded; it calls IMoaMmXAsset::StreamInMedia()if property data is needed.

If you have no data or if it's already freed, return kMoaErr_NoErr. The host then assumes that data needs to be loaded if it is needed in a subsequent operation. Return kMoaMmErr_FreeFailed if you failed to free your data; this notifies the host application that your data is still in memory.


GetDefaultRect()

Syntax

GetDefaultRect(PIMoaMmXAssetThis,
PMoaRectpRect)

Parameters

This
Pointer to the IMoaMmXAsset interface

pRect
PMoaRectPointer to a MoaRect to receive the default rectangle

Returns

kMoaErr_NoErr Successful
kMoaMmErr_NotImplemented Asset doesn't require default rectangle (e.g., transition)

Description


Implement this method to provide the default bounding rectangle for the asset. This bounding rectangle is used by the host application when creating new sprites for the asset in the playback window. The coordinates (0,0) indicate the registration point of the asset. If the asset does not have a variable registration point, the default rectangle should always be supplied centered around (0,0), rather than top-left at (0,0).


GetInMemMediaSize()

Syntax

GetInMemMediaSize(PIMoaMmXAssetThis,
MoaUlong FAR *pSizeBytes)

Parameters

This
Pointer to the IMoaMmXAsset interface

pSizeBytes
MoaUlong FAR *Pointer to a MoaUlong to receive the in- memory size of the media asset

Returns

kMoaErr_NoErr Successful, value at pSizeBytes set

Description


Implement this method to inform the host application of the current memory use of your media asset in bytes. Upon return, the parameter pSizeBytes contains the size, in bytes, of memory currently occupied by the media data. If media is unloaded, return 0.


GetInMemPropsSize()

Syntax

GetInMemPropsSize(PIMoaMmXAssetThis,
MoaUlong FAR *pSizeBytes)

Parameters

This
Pointer to the IMoaMmXAsset interface

pSizeBytes
MoaUlong FAR *Pointer to a MoaUlong to receive in- memory size of property data

Returns

kMoaErr_NoErr Successful, value at pSizeBytes set

Description

Implement this method to inform the host application of the current memory use of your media asset in bytes. Upon return, the parameter pSizeBytes contains the size, in bytes, of memory currently occupied by the property data. If props are unloaded, you should return 0.

GetProp()

Syntax

GetProp(PIMoaMmXAssetThis,
MoaMmSymbolsymbol,
PMoaMmValuepPropValue)

Parameters

This
Pointer to the IMoaMmXAsset interface

symbol
MoaMmSymbolMoaMmSymbolrepresenting the property to get

pPropValue
PMoaMmValuePointer to MoaMmValue to receive the value requested

Returns

kMoaErr_NoErr Property exists, value returned
kMoaErr_BadParam Invalid pPropValue
kMoaMmErr_PropertyNotFound Property not supported by this asset
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

Implement this method to return values for any custom properties supported by your media asset. The symbol represents the requested property. Your Xtra should include an instance variable containing an array of symbols for the properties you support. You can then look up the value passed in to your Xtra, and use the index in the array to determine the property to access. If your asset supports the specified property, you should create the corresponding value, and place the results in the pPropValue parameter. The host application then assumes ownership of the value and is responsible for releasing it. GetProp() returns the error code kMoaMmErr_PropertyNotFound if it does not support the property represented by symbol.

GetStreamOutMediaSize()

Syntax

GetStreamOutMediaSize(PIMoaMmXAssetThis,
MoaUlong FAR *pSizeBytes)

Parameters

This
Pointer to the IMoaMmXAsset interface

pSizeBytes
MoaUlong FAR *Pointer to a MoaUlong to receive the storage size of the media asset

Returns

kMoaErr_NoErr Successful, value at pSizeBytes set

Description


Implement this method to inform the host application of the total amount of media data, in bytes, streamed out when your IMoaMmXAsset::StreamOutMedia() method is called. The host application uses this value to determine the optimal file layout when saving a file and to test for available memory when streaming out to memory, for example for copy and paste operations. If the asset has no media data to stream out, set the value at pSizeBytes to 0. If it is not possible to determine the size of the media data to be streamed out, you can set the value at pSizeBytes to -1. (The only disadvantage to supplying -1 is that the host application may not be able to store your media data as efficiently on disk when an in-place save operation occurs.)


GetStreamOutPropsSize()

Syntax

GetStreamOutPropsSize(PIMoaMmXAssetThis,
MoaUlong FAR *pSizeBytes)

Parameters

This
Pointer to the IMoaMmXAsset interface

pSizeBytes
MoaUlong FAR *Pointer to a MoaUlong to receive the total amount of property data

Returns

kMoaErr_NoErr

Successful, value at pSizeBytes set

Description

Implement this method to inform the host application of the total amount of properties data, in bytes, streamed out when the application calls your IMoaMmXAsset::StreamOutProps() method. The host application uses this value to determine the optimal file layout when saving a file and to test for available memory when streaming out to memory, for example for copy and paste operations. If the cast member has no properties data to stream out, set the value at pSizeBytes to 0. You cannot use the special -1 value for pSizeBytesfor properties data. You must supply the actual data size that would be streamed out in a subsequent call to IMoaMmXAsset::StreamOutProps().

ImageStaticThumb()

Syntax

ImageStaticThumb(PIMoaMmXAssetThis,
PIMoaMmGCpGC,
ConstPMoaRectpImageRect)

Parameters

This
Pointer to the IMoaMmXAsset interface

pGC
PIMoaMmGCPointer to IMoaMmGC interface for graphics context in which to draw

pImageRect
ConstPMoaRectPointer to MoaRect specifying location and size of thumbnail

Returns

kMoaErr_NoErr Successful, static thumb drawn
kMoaMmErr_NotImplemented Asset doesn't have a static thumb
kMoaMmErr_GCTypeNotSupported Doesn't support supplied GC type
kMoaErr_OutOfMem Couldn't draw due to memory error
kMoaMmErr_InternalError Couldn't draw due to an internal error

Description


Optionally implement this method to draw a static thumbnail image for an asset into the specified rectangle in the specified graphics context. This method gets called by the host application only if the cast member's capabilities kMoaMmAssetCaps_CanImageStaticThumb flag is set. pImageRect can contain a rectangle of any size or aspect ratio, however, thumbnails should be optimized for drawing speed and look their best at a 4 (horizontal) x 3 (vertical) aspect ratio. The supplied graphics context interface is owned by the caller and should not be released by this method.

Director 5.0 requires the ability to image animated thumbmails to screen graphics contexts; no caching is attempted for animated thumbmails. Therefore, it is not important that you support offscreen drawing for animated thumbnails; you need only support static thumbnails. Regardless of how you support thumbnails, you can claim to support both static and animated thumbmail drawing, then return KMoaMmErr_GCTypeNotSupported when called to draw if you find that you can't draw into the supplied GC.

It is recommended that you support offscreen thumbnail imaging for static thumbnails so these thumbnails can be cached. Caching static thumbs isn't performed in 5.0, but will be implemented in a future release. Support offscreen static thumbnail imaging for future compatibility.

If the Xtra requires media data be loaded in order to image the static thumbnail, set the kMoaMmAssetCaps_StaticThumbNeedsMedia asset capabilities flag in your asset capabilities registry entry.

When drawing in the native environment, be careful not to change any native drawing context settings, such as brush or pen type, colors, clip regions, and so on. Drawing outside of the supplied rectangle is not supported and may have unpredictable results.


InvokeAboutBox()

Syntax

InvokeAboutBox(PIMoaMmXAssetThis)

Parameters

This
Pointer to the IMoaMmXAsset interface

Returns

kMoaErr_NoErr Successful, property editor invoked.
kMoaMmErr_NotImplemented Class doesn't have a property editor
kMoaErr_OutOfMem Couldn't invoke due to memory error
kMoaMmErr_InternalError Couldn't invoke due to an internal error

Description

Optionally implement this method if to display an About Box dialog for your asset. Currently, it is assumed that the About Box dialog is modal, and that this method returns after the user presses OK. Typically, this method is called from Director when the user presses the "About Box|" button in the Xtra Cast Member or Transition Properties Dialog.

InvokeMediaEditor()

Syntax

InvokeMediaEditor(PIMoaMmXAssetThis,
PMoaMmModifyFlagspModifyFlags)

Parameters

This
Pointer to the IMoaMmXAsset interface

pModifyFlags
PMoaMmModifyFlagsPointer to a MoaMmModifyFlags to receive modify flags

Returns

kMoaErr_NoErr Successful, media editor invoked
kMoaMmErr_NotImplemented Class doesn't have a media editor
kMoaErr_OutOfMem Couldn't invoke due to memory error
kMoaMmErr_InternalError Couldn't invoke due to internal error

Description


Optionally implement this method if your asset displays a media editor user interface. Currently, it is assumed that this is a modal dialog, and that this method returns when the user presses the OK or CANCEL buttons. This method is responsible for updating the value at pModifyFlagsto describe what changes, if any, where made to the media or properties for the asset. Typically, this method is called from Director when a user double-clicks on a cast member thumbnail in the cast.

The following flags are valid for modifyFlags:

Value Description
kMoaMmModifyFlags_None No media or properties have changed
kMoaMmModifyFlags_Media Media data has been modified
kMoaMmModifyFlags_Props Properties data has been modified

InvokePropsEditor()

Syntax

InvokePropsEditor(PIMoaMmXAssetThis)

Parameters

This
Pointer to the IMoaMmXAsset interface

Returns

kMoaErr_NoErr Successful, property editor invoked.
kMoaMmErr_NotImplemented Class doesn't have a property editor
kMoaErr_OutOfMem Couldn't invoke due to memory error
kMoaMmErr_InternalError Couldn't invoke due to an internal error

Description


Optionally implement this method to display the property editor user interface for the cast member. Currently it is assumed that this is a modal dialog, and that this method returns when the user presses the OK or CANCEL buttons. However, changes to properties should not be committed until the FinishPropsEditor() method is called--this informs your Xtra if the user has cancelled changes through the host application's own properties panel. Typically, this method is called from Director when the user presses the "Options ... " button in the Xtra Cast Member or Transition Properties Dialog.

NewXActor()

Syntax

NewXActor(PIMoaMmXAssetThis,
PMoaVoid FAR *ppXActor)

Parameters

This
Pointer to the IMoaMmXAsset interface

ppXActor
PMoaVoid FAR *Pointer to either a PIMoaMmXSpriteActor or PIMoaMmXTransitionActor to receive the interface for the new actor

Returns

kMoaErr_NoErr Successful, actor created and initialized
kMoaErr_OutOfMem Couldn't create actor due to memory error
kMoaMmErr_InternalError Couldn't create actor due to internal error

Description


Implement this method to create a new actor instance for the asset. This method creates a new object supporting either IMoaMmXSpriteActor or IMoaMmXTransitionActor, depending on whether the actor type is kMoaMmActorType_Sprite or kMoaMmActorType_Transition. The interface is returned to the caller in ppXActor You must supply either a PIMoaMmXSpriteActor or a PIMoaMmTransitionActor. Do not supply a PIUnknown.
In both cases, the calling host application owns the returned actor instance and is responsible for disposing it through its Release() method.

Sprite Actors

For sprite-based asset types, this method is typically called by Director when playing or scrubbing a movie and the beginning of a new sprite span for your asset has been encountered. It is the responsibility of NewXActor() to create a new instance of a class supporting the IMoaMmXSpriteActor interface, initialize the instance (typically calling its Init() method), and return a PIMoaMmXSpriteActor for it in ppXActor.
Transition Actors
For transition-based asset types, this method is typically called by Director when a transition is encountered in the transition channel in the score, when a Lingo puppetTransition command is issued, or when displaying the transition dialog. In these cases, it is the responsibility of NewXActor() to create a new instance of a class supporting the IMoaMmXTransitionActor interface, initialize the instance, and return a PIMoaMmXTransitionActor for it in it ppXActor.


Notify()

Syntax

Notify(PIMoaMmXAssetThis,
MoaLongmsgCode,
PMoaVoidrefCon)

Parameters

This
Pointer to the IMoaMmXAsset interface

msgCode
MoaLong

refCon
PMoaVoid

Returns

kMoaErr_NoErr Notification successful
kMoaMmErr_UnknownNotifyMsgCode Notify message code not supported

Description


ptionally implement this method to provide communication from actors to their assets. The sprite callback method lets you send arbitrary messages from your actor to its asset through this method.

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


PrepareNewContent()

Syntax

PrepareNewContent(PIMoaMmXAssetThis,
MoaMmNewFlagsnewFlags)

Parameters

This
Pointer to the IMoaMmXAsset interface

newFlags
MoaMmNewFlags

Returns

kMoaErr_NoErr Successful.
kMoaErr_OutOfMem Couldn't initialize due to memory error
kMoaMmErr_AssetCreationFailed User canceled or internal error

Description


Prepares new content for the asset. This method is called when a new asset is created in the host application. This method is called after the IMoaMmXAsset instance is created, whether the user chooses to create a new asset in the authoring environment or a new asset is created programatically. This method allows Xtras to prepare default media and properties for a new asset. After calling this function, the host application assumes that the property and media data for the object is loaded, so that it is not necessary to call StreamInProps() or StreamInMedia() to load any data from disk (because there isn't any on disk yet). Note that when a previously-saved asset is read-in when a document is opened, this method is not called. The method is used only when new assets are created in the authoring environment or when created programatically at playback time.

There are times when an Xtra should not invoke the user interface with this method, for example, when a Lingo programmer is creating a new asset programatically and does not want to display the asset creation or to preview the user interface. In this case, the asset should initialize itself with default properties and media without requiring any input from the user.

The bits in newFlags specify whether the asset can display a user interface for editing properties and media, and whether it was created through the user interface of an authoring tool or programatically (for example, with Lingo in Director).

In Director 5.0, these two values always are the same value, however in the future they may be independent to allow for such things as the programmatic creation of assets with user interfaces invoked for each asset.

The following flags are valid for newFlags:

Value Description
kMoaMmNewFlags_None No bits are set. If not specified, this field can be a combination of the following flags:
kMoaMmNewFlags_UiPermitted If set, the host application permits the display o f UI (such as a modal dialog) during this method call, which might be used to supply a preview or set initial values for the Xtra. If not set, PrepareNewContent() should not invoke any UI, and instead silently set-up the initial default properties and media for the asset.
kMoaMmNewFlags_AuthorInvoked If set, the host application calls this method in response to a request from the user initiated through the host application's user interface (that is, the user selected your menu item). If not set, your asset is being created programatically or as a side-effect of some internal operation in the host application (such as duplicating an asset).

This method returns the following values:


ServiceImageAnimThumb()

Syntax

ServiceImageAnimThumb(PIMoaMmXAssetThis,
PIMoaMmGCpGC,
ConstPMoaRectpImageRect)

Parameters

This
Pointer to the IMoaMmXAsset interface

pGC
PIMoaMmGCPointer to IMoaMmGC interface for graphics context in which to draw

pImageRect
ConstPMoaRectPointer to MoaRect specifying location and size of thumbnail

Returns

kMoaErr_NoErr Successful, animation thumb serviced
kMoaMmErr_NotImplemented Class doesn't have an animation thumb
kMoaMmErr_GCTypeNotSupported Doesn't support supplied GC type
kMoaErr_OutOfMem Couldn't update due to memory error
kMoaMmErr_InternalError Couldn't update due to internal error

Description


Optionally implement this method to service an asset's thumbnail animation. For assets that register the ability to display animated thumbnails, this method is called repeatedly after calling BeginImageAnimThumb(). This method may be called at variable rates up to 60 times per second, so assets that need to regulate the speed of their animations should use system clock routines to check timing, and return from this method immediately when not imaging. A call to ServiceImageAnimThumb()doesn't necessarily have to image a frame of the thumbnail animation; it can simply return if it is not yet time to draw the next frame. Servicing may occur at a rate of less than 60 times per second depending on the speed of the processor and the time this method takes to execute. Service time should not exceed 100 ms. Typical thumbnail animation speed should be at the rate of 5 to 15 frames per second for graphics, and up to 30 frames per second for video. The animation sequence is terminated by the host application with a call to EndImageAnimThumb(). The supplied graphics context interface is owned by the caller and should not be released by this method.

Director 5.0 requires the ability to image animated thumbmails to screen graphics contexts; no caching is attempted for animated thumbmails. Therefore, it is not important that you support offscreen drawing for animated thumbnails; you need only support static thumbnails. Regardless of how you support thumbnails, you can claim to support both static and animated thumbmail drawing, then return KMoaMmErr_GCTypeNotSupported when called to draw if you find that you can't draw into the supplied GC.

It is recommended that you support offscreen thumbnail imaging for static thumbnails so these thumbnails can be cached. Caching static thumbs isn't performed in 5.0, but will be implemented in a future release. Support offscreen static thumbnail imaging for future compatibility.

If your Xtra requires that media data be loaded in order to image the animated thumbnails, set the kMoaMmAssetCaps_AnimThumbNeedsMediaasset capabilities flag in your asset capabilities registry entry.

When drawing in the native environment, be careful not to change any native drawing context settings, such as brush or pen type,colors, clip regions, and so on. Drawing outside of the supplied rectangle is not supported and may have unpredictable results.


SetCallback()

Syntax

SetCallback(PIMoaMmXAssetThis,
PIMoaMmAssetCallbackpAssetCallback)

Parameters

This
Pointer to the IMoaMmXAsset interface

pAssetCallback
PIMoaMmAssetCallbackPointer to an IMoaMmAssetCallback interface

Returns

kMoaErr_NoErr Callback interface set
kMoaMmErr_NotImplemented Callback interface not used

Description


Receives a PIMoaMmAssetCallback interface containing callback methods for the asset. In Director, this class also supports the IMoaDrAssetCallback interface providing Director-specific callbacks. This is called when the host application places an instance of the asset into its asset library (for example, the cast in Director).

To hold on to the callback interface, call AddRef() on the interface and store it in an instance variable.

For transitions, the asset instance may be created by the Transition Dialog, but the asset won't be placed in the cast (and thus, SetCallback() called) until the user presses the OK button and the transition cast member is created.


SetProp()

Syntax

SetProp(PIMoaMmXAssetThis,
MoaMmSymbolsymbol,
ConstPMoaMmValuepPropValue)

Parameters

This
Pointer to the IMoaMmXAsset interface

symbol
MoaMmSymbolMoaMmSymbolrepresenting the property to get

pPropValue
ConstPMoaMmValuePointer to MoaMmValue to receive the value requested

Returns

kMoaErr_NoErr Property exists and value was set
kMoaErr_BadParam Invalid pPropValue
kMoaMmErr_PropertyNotFound Property not supported by this asset
kMoaMmErr_InternalError Property exists, value ok, can't set due to other error
kMoaMmErr_NoMemForString Can't allocate memory for 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

Implement this method to set the values for any properties supported by your media asset. symbol represents the property being accessed. Your Xtra should include an instance variable containing an array of symbols for the properties you support. You can then look up the value passed in to your Xtra, and use the index in the array to determine the property to access. The host application owns the instance pPropValue. If your implementation keeps this instance in its unconverted form, you must call IMoaMmUtils::ValueAddRef() on it. The IMoaMmXAsset::GetProp() method returns the error code kMoaMmErr_PropertyNotFound if it does not support the property represented by symbol.

StreamInMedia()

Syntax

StreamInMedia(PIMoaMmXAssetThis,
PIMoaStreampInStream)

Parameters

This
Pointer to the IMoaMmXAsset interface

pInStream
PIMoaStreamPointer to IMoaStream interface to use for streaming in data

Returns

kMoaErr_NoErr Successful, media streamed in (or none to stream)
kMoaErr_OutOfMem Failed, media not streamed due to memory error
kMoaMmErr_StreamInFailed Failed, media not streamed due to internal error.

Description


Implement this method to stream in your asset's media data by utilizing methods of the supplied IMoaStream interface. The stream interface allows you to read the media data from an opaque storage object (typically a disk file or memory block) in arbitrary-sized chunks. The host application owns the stream interface, so you should not release it. Typically, streams are used for reading and writing data to disk files and transferring data between in-memory objects (such as copy and paste).

If your asset instance does not have any media data, it can return from this call (with kMoaErr_NoErr) without utilizing the stream. See the documentation for IMoaStream for more details. Returning kMoaErr_NoErr indicates to the host application that this asset's media data has been successfully loaded. Returning kMoaMmErr_StreamInFailed indicates to the host application that your media are not loaded, causing it to call this method again the next time the data is needed. If you cannot load your data due to a broken link or some other problem not related to the amount of free RAM, you should track this case internally in your asset instance. Return kMoaErr_NoErr to signal that you don't want to be called again to load, or the host application calls this method repeatedly until data is streamed-in data successfully.

Note: Xtra developers should ensure proper byte ordering of data as it is streamed in and out. Intel and Motorola processors implement multibyte data types with different byte ordering. If you create cross-platform assets, you must ensure that data written on one platform and read on another is restored to the format appropriate to the host.


StreamInProps()

Syntax

StreamInProps(PIMoaMmXAssetThis,
PIMoaStreampInStream)

Parameters

This
Pointer to the IMoaMmXAsset interface

pInStream
PIMoaStreamPointer to IMoaStream interface to use for streaming in property data

Returns

kMoaErr_NoErr Successful, properties streamed in (or none to stream)
kMoaErr_OutOfMem Failed, properties not streamed due to memory error
kMoaMmErr_StreamInFailed Failed, properties not streamed due to internal error

Description


Streams in your asset property data by utilizing the supplied IMoaStream interface. The stream interface allows you to read property data from an opaque storage object (typically a disk file or memory) in arbitrary-sized chunks. The host application owns the stream interface, so you should not release it. Streams are typically used for reading and writing data to disk files and transferring data between in-memory objects (such as copy and paste). If the asset instance does not have any property data, it can return from this call (with kMoaErr_NoErr) without utilizing the stream.

See the documentation for IMoaStream for more details. Return kMoaErr_NoErr to indicate to the host application that the asset properties data have been loaded successfully

Return kMoaMmErr_StreamInFailed to indicate to the host application that your properties are not loaded. This causes the host application to call this method again the next time the properties are needed. If you cannot load your data because of a broken link or some other problem not related to amount of free RAM, you should track this case internally in your asset instance. Return kMoaErr_NoErrto signal that you don't want to be called again to load, otherwise, the host application calls repeatedly until you stream-in data successfully.

Note: Xtra developers should ensure proper byte ordering of data as it is streamed in and out. Intel and Motorola processors implement multibyte data types with different byte ordering. If you create cross-platform assets, you must ensure that data written on one platform and read on another is restored to the format appropriate to the host.


StreamOutMedia()

Syntax

StreamOutMedia(PIMoaMmXAssetThis,
PIMoaStreampOutStream)

Parameters

This
Pointer to the IMoaMmXAsset interface

pOutStream
PIMoaStreamPointer to IMoaStream interface to use for streaming out data

Returns

kMoaErr_NoErr Successful, media streamed out or no media to stream
kMoaMmErr_StreamOutFailed Failed, media not streamed out due to internal error

Description


Streams out the asset media data by utilizing the supplied IMoaStream interface. The stream interface allows you to write your media data to an opaque storage object (typically a disk file or memory block) in arbitrary-sized chunks. The host application owns the stream interface, so you should not release it. Streams are typically used for reading and writing data to disk files or transferring data between in-memory objects (such as copy and paste). If your asset instance does not have any media data, it can return from this call (with kMoaErr_NoErr) without utilizing the stream. See the documentation for IMoaStream for more details.

Return kMoaMmErr_StreamOutFailed from your IMoaMmXAsset::StreamOutMedia() method if you were unable to stream out your data. The host application will post a user alert, if appropriate (but will not cancel streaming out of other media elements if performing a save operation). By returning this error from StreamOutMedia, you signal that your media data has not yet been saved. If the host application is performing a save, it keeps your media data non-purgeable if it was edited since the last save.

Director note: The IMoaStream instance passed to you supports backwards seeking in the stream, but cannot subsequently resume writing data at the end of the stream. Thus, you should only use seeking for special cases such as writing a header at the beginning of the stream after all media data has been written.

Note: Xtra developers should ensure proper byte ordering of data as it is streamed in and out. Intel and Motorola processors implement multibyte data types with different byte ordering. If you create cross-platform assets, you must ensure that data written on one platform and read on another is restored to the format appropriate to the host.


StreamOutProps()

Syntax

StreamOutProps(PIMoaMmXAssetThis,
PIMoaStreampOutStream)

Parameters

This
Pointer to the IMoaMmXAsset interface

pOutStream
PIMoaStreamPointer to the IMoaStream interface to use for streaming out property data

Returns

kMoaErr_NoErr Successful, static thumb drawn
kMoaMmErr_NotImplemented Asset doesn't have a static thumb
kMoaMmErr_GCTypeNotSupported Doesn't support supplied GC type
kMoaErr_OutOfMem Couldn't draw due to memory error
kMoaMmErr_InternalError Couldn't draw due to an internal error

Description


Streams out the asset property data by utilizing the supplied IMoaStream interface. The stream interface allows you to write your property data to an opaque storage object (typically a disk file or memory) in arbitrary-sized chunks. The host application owns the stream interface, so you should not release it. Streams are typically used for reading and writing data to disk files or transferring data between in-memory objects (such as copy and paste). If your asset instance does not have any property data, it can return from this call (with kMoaErr_NoErr) without utilizing the stream.

See the documentation for IMoaStream for more details.

Director note: The IMoaStream instance passed to you supports backwards seeking in the stream, but cannot subsequently resume writing data at the end of the stream. Thus, you should only use seeking for special cases such as writing a header at the beginning of the stream after all media data has been written.

Note: Xtra developers should ensure proper byte ordering of data as it is streamed in and out. Intel and Motorola processors implement multibyte data types with different byte ordering. If you create cross-platform assets, you must ensure that data written on one platform and read on another is restored to the format appropriate to the host.

Important: You must supply the exact size of the property data to be streamed out in a subsequent call to IMoaMmXAsset::StreamOutProps(). The -1 value, which is acceptable for media data size, is not supported here.

Return kMoaMmErr_StreamOutFailed from your IMoaMmXAsset::StreamOutProps() method if you were unable to stream out your data. The host application will post a user alert, if appropriate, but will not cancel streaming out of other media elements if doing a save. By returning this error from IMoaMmXAsset::StreamOutMedia, you signal that your media data has not yet been saved out. If the host application is performing a save, it keeps your media data non-purgeable if it was edited since the last save.

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