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

IMoaDrCastMem

Interface ID: IID_IMoaDrCastMem
Pointer type: PIMoaDrCastMem
Inheritance: IMoaDrMediaOwner
Header file: driservc.h

Description

The IMoaDrCastMem interface provides access to specific cast members within a cast.
Cast member properties
IMoaDrCastMem inherits from the IMoaMmPropOwner interface, providing for access to data through the properties mechanism described in the "Multimedia Services" chapter in the Development Guide document. See the "Properties" section for information on the properties defined for objects providing the IMoaDrCastMem interface.
Cast member media types
Because this interface inherits from IMoaDrMediaOwner , you can use it to access the properties and media data associated with a cast member.

Methods of the IMoaDrMediaOwner interface include pointers to a MoaDrMediaInfo structure as parameters. Before a GetMedia(), SetMedia(), or AttachMedia() call, use IMoaDrUtils::NewMediaInfo() to fill out the structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the options field. Using this call forces you to fill out all the needed parameters. The aux information currently applies only when setting image media.
The formatSymbol and labelSymbol members of this structure are MoaMmSymbols. These symbols are obtained from strings using the host app symbol dictionary, accessed through the StringToSymbol() method of the IMoaMmUtils interface For more on how this mechanism is implemented, see the IMoaDrMediaOwner.
Here's a brief summary of the media labels supported for Director cast members:
Media Label Description
Composite Cast member media data in a portable (byte-swapped) opaque handle.
Image Primary image data (for a bitmap, PICT, and so on).
Text Text character string
TextStyles Text style run data
Sound Sound samples
Palette Palette entries
Score Score data for a movie or film loop

The following table provides a brief summary of the media formats supported for Director cast members.
Media Format Description
moaHandle Generic MoaHandle of data
moaTEStyles textStyles stored in a MoaHandle
macTEStyles textStyles in TextEdit StScrpHandle format stored in a Macintosh handle
macPICT Macintosh PicHandle. Note that 32bit images have alpha channel data.
macSnd Macintosh sndHdl. Handle in Macintosh sound resource format.
macColorTable Macintosh CTabHandle. Handle to a ColorTable record
winDIB Windows packed DIB GlobalHandle with bitmap information, color table, and bits. Note that 32bit images have alpha channel data.
winWAVE Windows RIFF WAVE GlobalHandle. RIFF sound format.
winPALETTE Windows HPALETTE GlobalHandle. RIFF palette format

Composite media

All media types support the composite label; that is, you can get the media data for any cast member as a single, opaque portable MoaHandle. Because Director handles the byteswapping of these, they're safe to write out to disk and read back in on another platform. The format for composite media is always MoaHandle.

Other media

In addition to composite, each built-in cast member type supports one or more other labels or formats. For example, bitmaps, PICTs, Rich Text, and OLE support the image label (RichText and OLE are Get-only for this); the bitmap format supported depends on the platform (macPICT on mac, winDIB on Windows). In the future, we may add additional formats, such as a portable pixel map format which is identical on both platforms.

Text supports multiple labels: text to get or set the ASCII text, textStyles (Macintosh-only) to get or set the style data independently from the ASCII.

Both movies and cast members support the score media label, with the format MoaHandle. This lets you get and set the score data itself. You can attach a ScoreAccess interface to one of these data handles using IMoaDrUtils::NewScoreAccess(). However, if you want to edit the score of an existing movie or cast member, it's easier just to obtain the ScoreAccess interface directly from the object itself using IMoaDrCastMem::GetScoreAccess(),

Here's a complete list of the media labels and formats supported by the Director cast member types:

Cast member type Media label Media format
BITMAP Composite
Image
moaHandle
mac: macPICT
win: winDIB
FILMLOOP Composite
Score
moaHandle
moaHandle
TEXTFIELD Composite
Text

TextStyles
moaHandle
moaHandle (null-terminated string)
mac: macTEStyles
mac & win: moaTEStyles
PALETTE Composite
Palette
moaHandle
mac: macColorTable
win: winPALETTE
PICT Composite
Image
moaHandle
mac: macPICT
win: winDIB
SOUND Composite
Sound
moaHandle
mac: macSnd
win: winWAVE
BUTTON Composite
Text

TextStyles
moaHandle
moaHandle (null-terminated string handle)
mac: macTEStyles
mac & win: moaTEStyles
SHAPE Composite moaHandle
MOVIE Composite moaHandle
DIGITAL VIDEO Composite moaHandle
SCRIPT Composite moaHandle
NOTE: Script text can be accessed using GetProp() and SetProp()
RICH TEXT Composite
Text

Image (Get Only)
moaHandle
moaHandle (null-terminated string handle). Set allowed only in authoring applications
mac: macPICT
win: winDIB
OLE Composite
Image (Get Only)
moaHandle
mac: macPICT
win: winDIB
XTRA Composite moaHandle
TRANS Composite moaHandle

Media access in sprite Xtras

Sprite Xtras, which provide cast members through extensions to Director, only support the composite media label, which is a combination of the Xtra's media, properties, and built-in properties combined in an opaque format. You can get or set the media data of any Xtra-based cast member type as a composite MoaHandle.

Methods

Property owner methods
GetProp()
SetProp()
Media owner methods
GetMedia()
SetMedia()
AttachMedia()
Scripting Support
CallFunction()
CallHandler()
Member information
GetMemberIndex()
Acquiring IMoaMmScoreAccess
GetScoreAccess()

AttachMedia()

Syntax
AttachMedia(PMoaDrMediaInfo pMediaInfo)
Parameters
pMediaInfo
Pointer to a caller- owned media information structure
Returns
MoaError
Description
Attaches media to a cast member, releasing it from the caller. This is the same as the SetMedia() method except instead of copying the data, it is moved to the cast member. (In effect this method is a SetMedia() call followed by a ReleaseMedia() call.)

Before making this call, use IMoaDrUtils::NewMediaInfo() to fill out the media information structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the options field.

On enter, the labelSymbol and formatSymbol fields should be populated with symbols indicating which chunk of media is to be attach (labelSymbol), and what format the media is supplied in (formatSymbol). The mediaData field should hold the data itself (typically a MoaHandle , Macintosh Handle, or Windows global handle)

Upon return, if there is no error, the media has changed ownership and belongs to the host application, and should no longer be referenced by the caller. This method is provided to allow the host application to optimize media-transfer if possible; it may prevent an extra copy of the media data, which may occur with separate SetMedia() and ReleaseMedia() calls).

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 the Xtra instance 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
MoaError
kMoaErr_NoErr Successful
kMoaMmErr_FunctionNotFound Function not supported
kMoaMmErr_WrongNumberOfArgs Argument count wrong,
Other Property/CallHandler errors Also acceptable here
Description
Calls a cast member Lingo function. Pass 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]. If the method has a return value, it should populate pResult with a new MoaMmValue containing the result. If the cast member does not support the function specified by methodName, it returns the error code kMoaMmErr_FunctionNotFound. If the number or types of arguments are incorrect, the function returns one of the appropriate MoaMmErrors (see mmtypes.h).

CallHandler()

Syntax
CallHandler(MoaMmSymbol handlerName, MoaLong nArgs, ConstPMoaMmValue pArgs, PMoaMmValue pResult, MoaBool * pHandled)
Parameters
handlerName
Symbol for handler (message) name
nArgs
Number of arguments you're passing
pArgs
Pointer to an array of MoaMmValues containing arguments
pResult
Pointer to a caller-owned MoaMmValue to receive the return value
pResult
Pointer to a MoaBool to receive TRUE if the handler exists in the script (message handled), or FALSE if it does not
Returns
MoaError
Description
Calls a handler handlerName defined in the script associated with this cast member. The nArgs argument is the number of arguments to the handler, the pArgs argument is a reference to the start of the array of arguments as MoaMmValues. You must pass in NULL to pResult if you do not expect a result. You must pass in a valid pointer if you do expect a result. The handler call will be passed up the standard Lingo messaging hierarchy. The argument pHandled reports whether the handler was handled by any object in the hierarchy.

GetMedia()

Syntax
GetMedia(PMoaDrMediaInfo pMediaInfo)
Parameters
pMediaInfo
Pointer to a caller-owned media information structure
Returns
MoaError
Description
Gets cast member media data. This method obtains a copy of the media associated with a cast member. Before making this call, use IMoaDrUtils::NewMediaInfo() to fill out the media information structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the options field. The caller partially populates a MoaDrMediaInfo struct with symbols indicating the requested chunk of media (labelSymbol) and the requested format (formatSymbol). After the call, the mediaData field is populated with the requested data; the type of this field depends on the format requested. The caller then owns the data and is responsible for disposing it, if applicable. Typically this data is either a MoaHandle, a Macintosh Handle or Pointer, or a Windows global handle.

You can use a Castmember GetMedia call to get either a PICT (on Mac) or a DIB (on Win). If you're querying a 32-bit member, you'll get back the alpha channel in the data. You can manipulate the image, and then set it back using SetMedia.

GetMemberIndex()

Syntax
GetMemberIndex(MoaDrMemberIndex * pMemberIndex)
Parameters
pMemberIndex
Pointer to position of cast member in cast
Returns
MoaError
Description
Returns the position of the cast member in its cast.

GetProp()

Syntax
GetProp(MoaMmSymbol symbol, PMoaMmValue pPropValue)
Parameters
symbol
The MoaMmSymbol for the property of interest
pPropValue
Pointer to a caller-owned MoaMmValue structure to receive the value of the property
Returns
MoaError
kMoaErr_NoErr Property exists and value was returned
kMoaErr_BadParam Invalid pPropValue passed in
kMoaMmErr_PropertyNotFound Property isn't supported by this class
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
Obtains the value of the specified player property. To get the symbol from a string, use the IMoaMmUtils::StringToSymbol(). The caller is responsible for releasing the value with IMoaMmUtils::ValueRelease() when it is no longer needed.

GetScoreAccess()

Syntax
GetScoreAccess(struct IMoaDrScoreAccess ** ppScore)
Parameters
ppScore
Address of place to return the interface
Returns
MoaError
Description
Obtains a IMoaDrScoreAccess interface for accessing or editing the score associated with a film loop cast member. This method is only valid for film loop cast members

SetMedia()

Syntax
SetMedia(PMoaDrMediaInfo pMediaInfo)
Parameters
pMediaInfo
Pointer to a caller-owned media information structure
Returns
MoaError
Description
Sets cast member media data. This method copies caller-supplied media data and associates it with a cast member. Before making this call, use IMoaDrUtils::NewMediaInfo() to fill out the media information structure, specifying NULL for the aux field and kMoaDrMediaOpts_None for the options field. The caller populates a MoaDrMediaInfo structure with symbols indicating the supplied chunk of media (labelSymbol), the supplied format (formatSymbol), and the media data itself (mediaData). If the label and format are supported by the cast member, a call to this method copies the caller's data and replaces any existing media data for the supplied label for the cast member. Since the data is copied, the caller retains ownership of the media data passed in. Typically, this data is either a MoaHandle, a Macintosh Handle or pointer, or a Windows global handle.

SetProp()

Syntax
SetProp(MoaMmSymbol symbol, ConstPMoaMmValue pPropValue)
Parameters
symbol
The MoaMmSymbol for the property of interest
pPropValue
Pointer to a caller-owned MoaMmValue structure to copy the new value for the property from
Returns
MoaError
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--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 value expected
Description
Sets a player property to a new value. To get the symbol from a string, use the IMoaMmUtils::StringToSymbol(). The caller continues to maintain ownership of the value passed in, and should release it using IMoaMmUtils::ValueRelease() when it is no longer needed.

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