The Multimedia support API is defined by various interfaces. Some of these are callback interfaces, that provide services through the callback object of the host application. Others are general purpose interfaces that can be implemented by either the host application or by an Xtra.
Multimedia services are provided to Xtras through a set of standard interfaces. Director provides the multimedia service callbacks for use by the various types of multimedia Xtras it supports, such as Asset, Tool, and Scripting Xtras.
Values, including properties, arguments to functions, and other data, are
passed to and from the host application through object-like entities of type
MoaMmValue. The IMoaMmPropOwner
interface provides a general mechanism for getting and setting data values from
an object. This interface is supported by media assets and by the Director callback
interfaces for accessing movie and media data. The IMoaMmValue
service interface supports converting data from MoaMmValue types
to standard C types. In addition , the IMoaMmColor
interface supports conversion of colors to values and starting with D8.5 the
IMoa3dVectorValueUtils
is used to convert between values and vectors. The IMoaMmList
interface supports creating, maintaining, and accessing lists of values. These
lists can be useful to chunk data for passing between a host application and
an Xtra.
For asset Xtras, the IMoaMmPropOwner interface is discussed in
"Asset Xtras." For Director media data access,
IMoaMmPropOwner is discussed in "Director
Support API."
Provided through various methods of the multimedia API, the IMoaMmGC interface represents a graphics context for Xtras to use to draw. This platform-independent interface provides access to platform-specific information about the drawing environment. The IMoaMmUtils2 and IMoaMmColor interfaces provide methods for converting between index values and color values in the current color palette. Starting with Director 8.5, the IMoaMmImage interface provides access to the image interface used to create and manipulate image objects.
The IMoaMmWndMac and IMoaMmWndWin interfaces provides a number of methods for presenting and managing platform-specific windows and dialog boxes.
The IMoaMmAssetCallback2
and IMoaMmSpriteCallback
interfaces are provided to media asset and sprite actor objects
when they are created. These enable the asset or actor to inform
the host application of changes that require the application to
draw or save it. These interfaces are discussed in "Asset Xtras."
The remainder of this discussion focuses on the multimedia API
that supports data conversion, imaging, and user interface management.
It begins by describing how to acquire the service interfaces
described in throughout.
Many of the multimedia services are provided by interfaces implemented
in the callback class of the host application. To acquire an instance
of the interface, your MOA objects can call QueryInterface()
on their pCallback instance variable, which represents
the application's callback interface. For example, to acquire
the IMoaMmUtils2 interface in C++:
pCallback->QueryInterface(&IID(IMoaMmUtils2), (PPMoaVoid)&pMmUtils2)
The multimedia interface IMoaMmPropOwner provides the methods GetProp() and SetProp() for accessing data provided by objects of various types. A number of interfaces inherit from IMoaMmPropOwner, including the IMoaMmXAsset and IMoaMmXSpriteActor multimedia Xtra interfaces and a number of Director-specific callabck interface (described in the next chapter). This allows the objects within an application and the objects provided by your Xtras to pass internal data in a uniform way.
When using the IMoaMmPropOwner interface, you pass values back and forth to the application using MoaMmValue structures. MoaMmValue types are object-like entities used to represent various types of data, including simple types such as integers, arrays such as strings, and complex types such as MoaPoints and MoaRects. The IMoaMmList interface is provided to manipulate a special type of MoaMmValue that supports creating, maintaining, and accessing lists of values. These list values are useful for representing complex types and variable length argument lists for passing between a host application and an Xtra.
Unlike data provided by a pointer or handle, you never access
data provided by a MoaMmValue directly. Instead, you
use methods provided by the IMoaMmValue
interface to test value types and convert data.
Because you access MoaMmValue data procedurally, you
need not lock and unlock data to access it. Like MOA interfaces,
the MoaMmValue mechanism uses reference counting to determine
when a value is in use and when it may be purged from memory.
Note: The methods discussed in this section can be implemented
by Xtras or by objects within an application, and ownership of
the MoaMmValues being passed depends on who's calling the method
that passes the value. The "Tips, Tricks, and Gotcha's"
discussion provides a general guidelines for ownership responsibilities
for MoaMmValues.
MoaMmValue types are used as parameters in a number of
callback and Xtra interfaces, most commonly through the GetProp()
and SetProp() methods of IMoaMmPropOwner,
from which many of these interfaces inherit.
When calling these methods, you convert between Moa and MoaMmValue
types using IMoaMmValue
methods such as ValueToFloat()/FloatToValue() and so
on. The following table lists all IMoaMmValue methods
for converting between Moa and MoaMmValue types:
Native type | Passing to an object | Receiving from an object |
MoaDouble | FloatToValue() | ValueToFloat() |
MoaLong | IntegerToValue() | ValueToInteger() |
MoaPoint | PointToValue() | ValueToPoint() |
MoaRect | RectToValue() | ValueToRect() |
MoaChar | StringToValue() | ValueToString() |
StringHandleToValue() | ValueToStringPtr()* | |
MoaMmSymbol** | SymbolToValue() | ValueToSymbol() |
*use IMoaMmValue::ValueReleaseStringPtr() to release
**use IMoaMmValue::StringToSymbol() to create the symbol
In addition to these types, the Director callback interface IMoaDrValue
provides methods for converting certain Director-specific types. Other value
conversion methods are available in the color and vector interfaces.
NOTE: palettes can be either CastMemRef (if they are
in the cast) or symbol (built in) data types.
Xtras may receive a MoaMmValue of unknown type, for example, as
an argument to a function they support in the host application's native scripting
language. The IMoaMmValue::ValueType()
method can test the type of a value before attempting to convert it.
To support imaging in Xtras, the IMoaMmUtils2 interface provides several methods for creating graphics contexts and for color palette lookup. In addition, the IMoaMmGC interface provides a platform-independent representation of platform-specific drawing information and imaging operations. The image interface IMoaMmImage provides a way to manipulate image objects - this is available in Director 8.5 and later.
The IMoaMmGC interface provides a graphics context for Xtras that need to draw themselves. This interface is provided through methods of several interfaces.
Among the Xtra interface methods that get instances of IMoaMmGC
are the thumbnail drawing methods of IMoaMmXAsset,
the IMoaMmXSpriteActor::Image()
method, and the transition drawing methods of IMoaMmXTransitionActor.
These methods are discussed in the previous chapter, "Asset
Xtras."
In addition, an Xtra can acquire an instance of this interface
for drawing in an arbitrary window or offscreen bitmap through
the IMoaMmUtils2::NewGC()
method. Call this method after acquiring a reference to the window
or offscreen bitmap you wish to draw in using standard system
calls.
When you call IMoaMmUtils2::NewGC(), you provide a MoaMmNativeGCInfo
structure that describes the system specific window or bitmap
you have acquired for drawing. This union provides a way to specify
details of windows, DIBs, and DDBs in Windows, and windows and
GWorlds on the Macintosh.
When you acquire an IMoaMmGC interface by calling IMoaMmUtils2::NewGC(),
it belongs to your Xtra. Be sure to call IMoaUnknown::Release()
on it when you are through using it.
One of the main uses for the IMoaMmGC interface is to
enable an Xtra to draw into its own offscreen buffer, then copy
the buffer into a graphics context of the host application. To
do so, you set up your offscreen buffer using standard system
calls, then create an IMoaMmGC for it using IMoaMmUtils2::NewGC().
You can then draw in your buffer using platform-specific graphics
operations. When drawing is complete, you can transfer it to another
graphics context by calling IMoaMmGC::Blit()
on the destination context, providing your context as the source.
Blitting between contexts is particularly useful in the animation
loop of an sprite asset Xtra. In its IMoaMmXAsset::Event()
method, your sprite actor could respond to step events by updating
the image in its offscreen buffer. Within your Image()
method, you would use IMoaMmGC::Blit() to copy pixels
from the offscreen buffer into the graphics context passed to
you by Image(). You could use a similar technique to
copy the contents of a window rectangle--for example, a media
editor window--into another IMoaMmGC.
The Blit() method supports various ink modes. Some of the pixel
transfer behavior provided by this method may be application-specific.
The IMoaMmUtils2 interface provides two methods for converting
between index values and color values in the current color palette:
IndexToRGB()
and RGBToIndex().
These methods work reliably only when system pixel depth is set
to less than or equal to 8 bits. They don't support direct-color
systems.
IndexToRGB() takes a color palette index and returns the RGB value
located at the corresponding position in the palette. RGBToIndex()
takes an RGB value and returns the index of the closes matching color in the
current palette. You must use these instead of the platform-specific palette
lookup API (such as Color2Index() and Index2Color()
on the Macintosh). This ensures that your Xtra gets the proper color palette
lookup results regardless of any behind-the-scene palette manipulation going
on in the host application.
The IMoaMmWndMac
and IMoaMmWndWin
interface provides a number of methods for presenting and managing
platform-specific windows and dialog boxes.
Methods of the IMoaMmWndMac and IMoaMmWndWin
interface allow you to present standard system dialog boxes, both
Macintosh and Windows. Director also implements methods that support
non-modal windows.
Note: You must use the API described here rather than standard
platform-specific API for dialog and windows management. This
ensures that your Xtra's windows synchronize with the window management
capabilities provided by the host application.
Note: You may want to use the MUI Xtra API to implement user interface dialogs. This API provides a platform-independent way to display dialogs and to respond to user events. Consult the MUI Xtra API documentation for information on which applications support it.
On the Macintosh, modal dialogs are handled through the IMoaMmWndMac
and IMoaMmWndWin methods MacPrepareModalDialog(),
MacModalDialog(),
and MacUnprepareModalDialog().
You call these methods in sequence to coordinate event handling
and window display with the host application. The MacPrepareModalDialog()
method returns a dialogCookie parameter that you must
in turn pass to the MacModalDialog() method.
MacModalDialog() replaces the standard Macintosh system call ModalDialog(),
providing similar parameters. Be sure to call IMoaCallback::MoaBeginUsingResources()
and IMoaMmWndMac::MacPrepareModalDialog() before calling MacModalDialog().
Call IMoaMmWndMac::MacPrepareModalDialog() and IMoaCallback::MoaEndUsingResources()
after exiting the dialog's event handling loop and hiding the dialog.
In Windows, modal dialogs are handled through the IMoaMmWndWin
methods WinDialogBox()
or WinDialogBoxParam(),
which replace the standard Windows system calls DialogBox()
and DialogBoxParam(). WinDialogBoxParam() enables
you to pass in an arbitrary 32-bit value as a parameter. Use this
method to pass a data structure or interface to your dialog process
if you need to access information of the Xtra. Be sure to call
IMoaCallback::MoaBeginUsingResources()
before calling WinDialogBox()or WinDialogBoxParam(),
and call IMoaCallback::MoaEndUsingResources()
after exiting these methods.
Windows supports a variety of dialog box creation functions. The
methods WinPrepareDialogBox()
and WinUnprepareDialogBox()
are provided as brackets to let you call any of these standard
Windows dialog box calls. When you use the standard Windows creation
API, you call these methods to coordinate event handling and window
display with the host application. Call WinPrepareDialog()
before calling a Windows dialog box function, then call WinUnprepareDialogBox()
after hiding the dialog box.
Note: The methods WinPrepareDialog() and WinUnprepareDialogBox() aren't required when you call the methods IMoaMmWndWin::WinDialogBox() and IMoaMmWndWin::WinDialogBoxParam(), which are implemented to handle the housekeeping internally.
IMoaMmWndMac
provides a number of methods that support standard (non-modal)
Macintosh windows. This enables an Xtra to put up floating palettes,
interactive editors, and other independent user interfaces. In
their general order of use, the methods provided are MacRegisterWindow(),
MacXShowWindow(), MacSelectWindow(), MacDragWindow(),
MacHideWindow() and MacUnregisterWindow().
Note: To synchronize your Xtra's windows with the window
management provided by the host application, you must always use
these methods, rather than the standard Mac toolbox calls, to
display modeless windows on the Macintosh.
In addition to these methods the multimedia API defines the IMoaMacEventHandler
Xtra interface. This interface is implemented by an Xtra to provide
an event handling routine to Macintosh windows.
The IMoaMmMacEventHandler
interface needs to be implemented by Xtras that display non-modal
Macintosh windows. For example, a media asset Xtra could implement
this interface to support non-modal media editing, with the implementation
provided by the class the implements IMoaMmXAsset.
However, be aware that if several non-modal windows are displayed
simultaneously, each requires its own instance of this interface
(and thus should be implemented in a separate class). This interface
consists of two methods, SetRegistered() and HandleEvent().
IMoaMmMacEventHandler::SetRegistered()
is called to notify your event handler when your window is registered
and unregistered. Implementation of this method is optional; implement
it if you need to initialize and dispose of memory required by
your HandleEvent() method. An arbitrary data handle,
refCon, is passed in to SetRegistered() and
subsequently passed to your HandleEvent() method each
time it is called.
IMoaMmMacEventHandler::HandleEvent()
is called by the host application to pass events that occur in
your window to your Xtra. Implement this method to interpret the
standard Macintosh event record--passed in as a parameter--and
perform the appropriate actions in response to the event.
Before you begin using a window on the Macintosh, you create it
using the standard Macintosh toolbox window creation calls NewWindow(),
NewCWindow(), GetNewWindow(), or GetNewCWindow().
Create your window as hidden.
Before you actually use the window, you register it with the host
application by calling IMoaMmWndMac::MacRegisterWindow().
In this method, you pass the IMoaMacEventHandler interface,
to enable the host application to call it to handle events in
your window. Registering enables the host to coordinate event
handling and window display with your Xtra.
After creating and registering your window, you can display it
and bring it to the front by calling IMoaMmWndMac::MacXShowWindow()
and IMoaMmWndMac::MacSelectWindow().
Don't use the standard system calls ShowWindow() and
SelectWindow() for these operations.
Once you've registered and displayed your window, your IMoaMmMacEventHandler::HandleEvent()
method is called each time a significant event occurs in the window.
In general, your implementation of HandleEvent() uses
standard techniques for handling the events. However, for correct
behavior, you should use methods of IMoaMmWndMac to handle
window dragging and event passing.
Call IMoaMmWndMac::MacDragWindow()
to drag the window. This method replaces the standard Mac toolbox
DragWindow() call, to ensure that other windows belonging
to the host application interact correctly with your window as
it moves.
Call IMoaMmWndMac::MacHideWindow()
to hide the window. This method replaces the standard Mac toolbox
HideWindow() call, to ensure that other windows belonging
to the host application interact correctly with your window when
it is hidden.
Call IMoaMmWndMac::MacXShowWindow()
to display your window. This method replaces the standard Mac
toolbox ShowWindow() call, to ensure that other windows
belonging to the host application interact correctly with your
window when it is displayed.
(Note that IMoaMmWndMac::MacHandleEvent()
is not intented for use with the modeless dialog API. If you were
to implement IMoaMmMacEventHandler::HandleEvent() to
call this method, you could get stuck in an infinite loop. This
method is intended primarily for passing update events to the
host application in other contexts.)
To close and dispose of a window, call the Macintosh DisposeWindow()
routine after the window is hidden and unregistered.
The sequence for disposing a window would be:
pUtils->lpVtbl->MacHideWindow(pUtils, theWindow)
pUtils->lpVtbl->MacUnregisterWindow(pUtils,
pMyEventHandler)
DisposeWindow(theWindow)
If you don't call MacHideWindow() before
the other calls, the host application's window management code
may be put in an inconsistent state.
Note: Never dispose of a window before unregistering it,
as this can cause the host application to crash.
The IMoaMmCuePointCallback interface provides a mechanism for sending notification to the host application when an Xtra encounters a specific cue point. This is useful to enable sprite Xtras and others to implement their internal mechanisms for recognizing cue points and informing the host.