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


Director Xtra Development Kit: Multimedia Developer's Guide

Multimedia Support API


Introduction

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

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.

Value access and data conversion

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."

Imaging support

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.

User interface support

The IMoaMmWndMac and IMoaMmWndWin interfaces provides a number of methods for presenting and managing platform-specific windows and dialog boxes.

Asset support

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.

Acquiring services interfaces

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)

Property access and data conversion

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.

The MoaMmValue type

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.

Using MoaMmValues

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.

Imaging support

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 graphics context interface

The IMoaMmGC interface provides a graphics context for Xtras that need to draw themselves. This interface is provided through methods of several interfaces.

Acquiring a graphics context

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.

Drawing in a graphics context

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.

Color palette lookup

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.

User interface support

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.

Macintosh dialogs

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.

Windows dialog boxes

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.

Macintosh non-modal windows

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.

Implementing IMoaMacEventHandler

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.

Creating, registering, and showing windows

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.

Handling events

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.)

Disposing of windows

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.

Cue Point Callbacks

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.


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