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

IMoaMmGC

Interface ID: IID_IMoaMmGC
Pointer type: PIMoaMmGC
Inheritance: IMoaUnknown
Header file: mmiservc.h

Description

This standard multimedia interface is provided by various Xtra interface methods that enable an object to draw itself, including the IMoaMmXAsset methods for drawing thumbnail images, the IMoaMmXSpriteActor::Image() method, and the IMoaMmXTransitionActor methods for performing a transition. You can also acquire a graphics context interface for doing other drawing by calling IMoaMmUtils::NewGC().

This interface provides both platform-independent and platform-specific access to the graphics context of the current platform. Methods in this interface provide information about the native operating system windows and offscreen buffers into which an Xtra should draw.

Methods

GetContentRect()
GetPixelDepth()
GetNativeGCInfo()
SetNativeGCInfo()
Blit()

Blit()

Syntax

Blit(PIMoaMmGCThis,

ConstPMoaRectpDestRect,
struct IMoaMmGC FAR *pSrcGC,
ConstPMoaRectpSrcRect,
MoaMmInkink,
ConstPMoaMmInkParamspInkParams,
PMoaVoidnativeClipRegion)

Parameters

This

Pointer to the IMoaMmGC interface

pDestRect

ConstPMoaRectConstPMoaRect representing the area to which to copy

pSrcGC

struct IMoaMmGC FAR *

pSrcRect

ConstPMoaRect

ink

MoaMmInk

pInkParams

ConstPMoaMmInkParamsOptional ConstPMoaMmInkParams specifying ink parameters

nativeClipRegion

PMoaVoidMacintosh RgnHandle or Window HRGN

Returns

MoaError

Description

If you're using Blit() within the Image() method of a IMoaMmXSpriteActor implementation, you can use the ink and inkParams from the SpriteInfo structure supplied to your Image() method. This allows you to support whatever ink mode (and parameters) which were specified by the user for your sprite easily. In Director, the ink and inkParams values are stored in each score cell.

The supported ink modes depend on the host application. Some host applications support only MoaMmInk_Copy. Blit()returns the error message kMoaMmErr_NotImplemented if you attempt to use an ink which is not supported by the host application. Always check the error code when using Blit(). If there's an error, the operation was not performed. Try the operation again specifying another ink.

Director 5.0's Blit() implementation supports all Director ink modes except Matte and Mask. You'll get the kMoaMmErr_NotImplemented error if you try to use those modes.

Director 5.0 supports Blend as well. You do a blend by specifying the blend amount (0-255) in the blendValue field of the inkParams. You must also set the obeyBlend field to TRUE.

In Director 5.0, the ink mode is ignored when doing a blend: a Copy-style blend is always performed. This behavior is slightly different from Director's ink support with bitmap cast members. For bitmap cast members, you can do a backgroundTransparent blend; with Director 5.0's Blit() method, a Copy-style blend is performed. . In future releases, Director 5.0's Blit() may support blend combined with various ink modes.

Colorization and transparent background operations are supported by Director 5.0's Blit(). Use a non-black foreground color to colorize the image. To use backgroundTransparent, set ink to kMoaMmInk_BackgroundTransparent and set bgColor to the color you to have the transparent effect.

If you want to use Blit() with your own window or offscreen buffer(s), use IMoaMmUtils::NewGC() to create a graphics context interface for an existing window or buffer that you own. Releasing the GC interface does not dispose of your window or buffer; you must do this yourself after releasing the GC.

Windows: In Director 5.0, ink modes other than kMoaMmInk_Copy are supported only if both graphics contexts are DIB-based. If either GC is a window or DDB DC, the ink mode is ignored and copy ink is used. Stretching and clipRegion, however, are still supported. Director 5.0's offscreen buffer is always a DIB on Windows.

See the InkTest Sprite Xtra sample for an example of creating a GC from an offscreen buffer and using the Blit() method to image a sprite.

In summary, the main differences between Director's ink support for bitmap cast members and ink support in Blit() include the following:

Blit() does not support mask or matte inks. If you try to use an unsupported ink, the error code kMoaMmErr_NotImplemented is returned and the operation fails.

Blit() does not support blends combined with inks. Blit()ignores the ink mode if obeyBlend is set, and performs a simple Copy-style blend. No error code is returned; the Blit operation occurs with the specified blendAmount and the ink mode is ignored. Blends combined with some ink modes (such as bgTransparent, matte, mask) may be supported in future releases.

Director may implement some ink modes differently than the Blit() method does. Blit() uses standard system ink modes, while Director uses internal code. Director supplies some ink modes combined with a Matte ink. As a result, images drawn with Blit() may have visible borders, while images drawn with Director have their borders matted out. The following list summarizes the ink modes that Blit() may draw somewhat differently than Director.

• Not Copy

• Not Transparent

• Not Reverse

• Not Ghost

• Darkest

• Lightest

• Add

• Add Pin

• Subtract Pin

GetContentRect()

Syntax

GetContentRect(PIMoaMmGCThis,

PMoaRectpContentRect)

Parameters

This

Pointer to the IMoaMmGC interface

pContentRect

PMoaRectPointer to a MoaRect to receive the graphics context bounds

Returns

MoaError

Description

Obtains a rectangle demarking the bounds of the drawing area of the graphics context and places it in the MoaRect pointed to by pContentRect.

GetNativeGCInfo()

Syntax

GetNativeGCInfo(PIMoaMmGCThis,

PMoaMmNativeGCInfopNativeGCInfo)

Parameters

This

Pointer to the IMoaMmGC interface

pNativeGCInfo

PMoaMmNativeGCInfoPointer to a MoaMmNativeGCInfo structure to receive the information

Returns

MoaError

Description

Obtains platform-specific graphics context information for the graphics context. This populates the PMoaMmNativeGCInfo structure supplied by the caller in pNativeGCInfo with platform-dependent information about the graphics context. The PMoaMmNativeGCInfo type is a union structure with variants for various platforms and window versus offscreen state.

GetPixelDepth()

Syntax

GetPixelDepth(PIMoaMmGCThis,

MoaLong FAR *pPixelDepth)

Parameters

This

Pointer to the IMoaMmGC interface

pPixelDepth

MoaLong FAR *Pointer to a MoaLong to receive the pixel depth.

Returns

MoaError

Description

Retrieves the a pixel depth of the graphics context. Possible values returned in pPixelDepth are 1, 2, 4, 8, 16, 24, and 32.

SetNativeGCInfo()

Syntax

SetNativeGCInfo(PIMoaMmGCThis,

ConstPMoaMmNativeGCInfopNativeGCInfo)

Parameters

This

Pointer to the IMoaMmGC interface

pNativeGCInfo

ConstPMoaMmNativeGCInfoPointer to a ConstPMoaMmNativeGCInfo

Returns

Description

Releases the current native information associated with the specified graphics context and sets new information.

Windows: If the existing graphics contexts is HWND-style and the handle to the device context is owned by the graphics context (that is, the graphics context and the device context are owned by the host application), the device context is released automatically when setting the new data. If the device context is owned by someone else (for example, NewGC() is used to create the graphics context), the new graphics context information replaces the old. The caller of NewGC()owns the original device context and should dispose of it after changing it with SetNativeGC(). You can dispose of the graphics context entirely using

pMyGC->lpVtbl->Release(pMyGC).