Derived Media Handler Support
This chapter describes the functions and constants that your derived media handler may support and the data structure that your component may use to interact with the base media handler.
Data Structure
The GetMovieCompleteParams data type defines the layout of the complete movie parameter structure used by the MediaInitialize function:
typedef struct { |
short version; /* version; always 1 */ |
Movie theMovie; /* movie identifier */ |
Track theTrack; /* track identifier */ |
Media theMedia; /* media identifier */ |
TimeScale movieScale; /* movie's time scale */ |
TimeScale mediaScale; /* media's time scale */ |
TimeValue movieDuration; /* movie's duration */ |
TimeValue trackDuration; /* track's duration */ |
TimeValue mediaDuration; /* media's duration */ |
Fixed effectiveRate; /* media's effective rate */ |
TimeBase timeBase; /* media's time base */ |
short volume; /* media's volume */ |
Fixed width; /* width of display area */ |
Fixed height; /* height of display area */ |
MatrixRecord trackMovieMatrix; /* transformation matrix */ |
CGrafPtr moviePort; /* movie's graphics port */ |
GDHandle movieGD; /* movie's graphics device */ |
PixMapHandle trackMatte; /* track's matte */ |
QTAtomContainer inputMap; /* media's input map */ |
} GetMovieCompleteParams; |
Field |
Description |
|---|---|
|
Specifies the version of this structure. This field is always set to 1. |
|
Identifies the movie that contains the current media's track. This movie identifier is supplied by the Movie Toolbox. Your component may use this identifier to obtain information about the movie that is using your media. |
|
Identifies the track that contains the current media. This track identifier is supplied by the Movie Toolbox. Your component may use this identifier to obtain information about the track that contains your media. For example, you might call the Movie Toolbox's |
|
Identifies the current media. This media identifier is supplied by the Movie Toolbox. Your derived media handler can use this identifier to read samples or sample descriptions from the current media, using the Movie Toolbox's |
|
Specifies the time scale of the movie that contains the current media's track. If the Movie Toolbox changes the movie's time scale, the toolbox calls your derived media handler's |
|
Specifies the time scale of the current media. If the Movie Toolbox changes your media's time scale, the toolbox calls your derived media handler's |
|
Contains the movie's duration. This value is expressed in the movie's time scale. |
|
Contains the track's duration. This value is expressed in the movie's time scale. |
|
Contains the media's duration. This value is expressed in the media's time scale. |
|
Contains the media's effective rate. This rate ties the media's time scale to the passage of absolute time, and does not necessarily correspond to the movie's rate. This value takes into account any master time bases that may be serving the media's time base. The value of this field indicates the number of time units (in the media's time scale) that pass each second. This rate is represented as a 32-bit, fixed-point number. The high-order 16 bits contain the integer portion, and the low-order 16 bits contain the fractional portion. The rate is negative when time is moving backward for the media. Whenever the Movie Toolbox changes your media's effective rate, it calls your derived media handler's |
|
Identifies the media's time base. |
|
Contains the media's current volume setting. This value is represented as a 16-bit, fixed-point number. The high-order 8 bits contain the integer portion; the low-order 8 bits contain the fractional part. Volume values range from -1.0 to 1.0. Negative values play no sound but preserve the absolute value of the volume setting. If the Movie Toolbox changes your media's volume, it calls your derived media handler's |
|
Indicates the width, in pixels, of the track rectangle. This field, along with the |
|
Indicates the height, in pixels, of the track rectangle. This value corresponds to the y coordinate of the lower-right corner of the rectangle and is expressed as a fixed-point number. |
|
Specifies the matrix that transforms your media's pixels into the movie's coordinate system. The Movie Toolbox obtains this matrix by concatenating the track matrix and the movie matrix. You should use this matrix whenever you are displaying graphical data from your media. Whenever the Movie Toolbox modifies this matrix, it calls your derived media handler's |
|
Indicates the movie's graphics port. Whenever the Movie Toolbox changes the movie's graphics world, it calls your derived media handler's |
|
Specifies the movie's graphics device. Whenever the Movie Toolbox changes the movie's graphics world, it calls your derived media handler's |
|
Identifies the matte region assigned to the track that uses your media. This field contains a handle to a pixel map that contains a blend matte. Your component is not responsible for disposing of this matte. If there is no matte, this field is set to |
|
A reference to the media's input map. The media input map should not be modified or disposed. |
Component Manager Flag
The Component Manager allows you to specify information about your component’s capabilities in the componentFlags field of the component description record. Within this field, the mediaHandlerFlagBaseClient flag indicates that your component is derived from another component. Setting this flag to 1 tells the Component Manager that your component is a client of the base media handler.
Functions
This section lists the functions that may be supported by derived media handler components.
Managing the Component
Derived media handlers provide three functions that allow the Movie Toolbox to manage its relationship with the media handler. The Movie Toolbox calls your MediaInitialize to give you an opportunity to prepare to provide access to your media. The Movie Toolbox grants processing time to your handler by calling your MediaIdle function. Your MediaGGetStatus function allows the Movie Toolbox to retrieve status information after calling MediaIdle.
General Data Management
While the base media handler isolates your component from the details of media data access, your derived media handler still needs to keep track of certain information in order to support movie playback and creation. This section discusses functions that help your media handler manage its information.
Your media handler may store proprietary information in its media. The Movie Toolbox calls two media handler functions in order to give you an opportunity to retrieve or store this information. The MediaPutMediaInfo function allows you to store your special information in your media. The MediaGetMediaInfo function delivers that data to your media handler.
The Movie Toolbox tells your media handler when its track has been enabled or disabled by calling your MediaSetActive function. The Movie Toolbox prepares your handler for playback by calling your MediaPreroll function. Whenever your media’s playback rate changes, the Movie Toolbox calls your MediaSetRate function. Whenever the track that uses your media is edited, the Movie Toolbox calls your MediaTrackEdited function.
If the Movie Toolbox has called its SetMediaSampleDescription function on a sample description, it uses the MediaSampleDescriptionChanged function to notify your media handler of the change.
The Movie Toolbox allows tracks to be identified by various characteristics. For instance, it is possible to request that all tracks containing audio information be searched. To determine whether a track has a given characteristic, the Movie Toolbox queries the media handler for each track. The Movie Toolbox calls the MediaHasCharacteristic function with the specified characteristic.
The Movie Toolbox uses two functions to inform you about changes to your media’s time environment. The MediaSetMediaTimeScale function allows the Movie Toolbox to change your media’s time scale. The MediaSetMovieTimeScale function allows the Movie Toolbox to tell you when the movie’s time scale has changed.
Other useful functions include
MediaGSetActiveSegmentMediaInvalidateRegionMediaGetNextStepTimeMediaTrackReferencesChangedMediaTrackPropertyAtomChangedMediaSetTrackInputMapReferenceMediaGetSampleDataPointerMediaReleaseSampleDataPointerMediaCompareMediaSetVideoParamMediaGetVideoParamMediaSetNonPrimarySourceDataMediaGetOffscreenBufferSizeMediaSetHintsMediaGetName
Graphics Data Management
If your media handler draws media data on the screen, you need to manage your media’s graphics environment. The Movie Toolbox uses a number of functions to inform you about changes to the graphics environment. The Movie Toolbox only calls these functions if you have set the handlerHasSpatial flag to 1 in the flags parameter of the MediaSetHandlerCapabilities function.
The Movie Toolbox calls your handler’s MediaSetGWorld function whenever your media’s graphics port or graphics device has changed. The MediaSetDimensions function allows the Movie Toolbox to inform your handler about changes to its spatial dimensions. Whenever either the movie or track matrix changes, the Movie Toolbox calls your MediaSetMatrix function. Similarly, if your media’s clipping region changes, the Movie Toolbox calls your MediaSetClip function.
When it is building up a movie’s image from its component tracks, the Movie Toolbox must be able to determine which tracks are transparent. The Movie Toolbox calls your MediaGetTrackOpaque function to retrieve this information about your media.
The Movie Toolbox calls your MediaGetNextBoundsChange function so that it can learn when your media will next change its display shape. When the Movie Toolbox wants to find out the shape of the region into which you draw your media, it calls your MediaGetSrcRgn function.
Other useful functions include
MediaGetDrawingRgnMediaGetGraphicsModeMediaSetGraphicsMode
Sound Data Management
The Movie Toolbox uses your MediaGSetVolume function to tell your media handler when its sound volume has changed. It uses MediaSetSoundLocalizationData to support 3D sound capabilities in a media handler that plays sound.
Base Media Handler Utility Function
Apple’s base media handler component provides a utility function, MediaSetHandlerCapabilities, which allows you to tell the base handler what your derived handler can do.
Management of Progressive Downloads
The function MediaMakeMediaTimeTable is called by the base media handler to create a media time table whenever an application or other software calls the Toolbox’s QTMovieNeedsTimeTable, GetMaxLoadedTimeInMovie, MakeTrackTimeTable, or MakeMediaTimeTable function. When an application or other software calls one of these functions, it allocates an unlocked relocatable memory block for the time table to be returned and passes a handle to it in the offsets parameter. Your derived media handler must resize the block to accommodate the time table it returns.
The time table your derived media handler returns is a two-dimensional array of long integers that is organized so that each row in the table contains values for one data reference. The first column in the table contains values for the time in the media specified by the startTime parameter, and each subsequent column contains values for the point in the media that is later by the value specified by the timeIncrement parameter. Each long integer value in the table specifies the offset, in bytes, from the beginning of the data reference for that point in the media.
Constants
The constants listed in this section support the functions listed in Functions.
Function Flags
/* flags in flags parameter of MediaSetHandlerCapabilities function */ |
enum { |
handlerHasSpatial = 1<<0, /* draws */ |
handlerCanClip = 1<<1, /* clips */ |
handlerCanMatte = 1<<2, /* reserved */ |
handlerCanTransferMode = 1<<3, /* does transfer modes */ |
handlerNeedsBuffer = 1<<4, /* use offscreen buffer */ |
handlerNoIdle = 1<<5, /* never draws */ |
handlerNoScheduler = 1<<6, /* schedules self */ |
handlerWantsTime = 1<<7, /* needs more time */ |
handlerCGrafPortOnly = 1<<8 /* color only */ |
}; |
/* values for inFlags parameter of MediaIdle function */ |
enum { |
mMustDraw = 1<<3, /* must draw now */ |
mAtEnd = 1<<4, /* current time |
corresponds to end of movie */ |
mPreflightDraw = 1<<5 /* must not draw */ |
}; |
/* values for outFlags parameter of MediaIdle function */ |
enum { |
mDidDraw = 1<<0, /* did draw */ |
mNeedsToDraw = 1<<2 /* needs to draw */ |
}; |
Component Types and Characteristics
/* component type and subtype values */ |
#define MediaHandlerType 'mhlr' /* derived media handler */ |
#define BaseMediaType 'gnrc' /* base media handler */ |
/* constants used in the characteristic parameter of the |
MediaHasCharacteristic function */ |
#define VisualMediaCharacteristic 'eyes' /* visual media characteristic */ |
#define AudioMediaCharacteristic 'ears' /* audio media characteristic */ |
Selectors
/* selectors for derived media handler components */ |
enum { |
kMediaInitializeSelect = 0x501, /* MediaInitialize */ |
/* MediaSetHandlerCapabilities */ |
kMediaSetHandlerCapabilitiesSelect = 0x502, |
kMediaIdleSelect = 0x503, /* MediaIdle */ |
kMediaGetMediaInfoSelect = 0x504, /* MediaGetMediaInfo */ |
kMediaPutMediaInfoSelect = 0x505, /* MediaPutMediaInfo */ |
kMediaSetActiveSelect = 0x506, /* MediaSetActive */ |
kMediaSetRateSelect = 0x507, /* MediaSetRate */ |
kMediaGGetStatusSelect = 0x508, /* MediaGGetStatus */ |
kMediaTrackEditedSelect = 0x509, /* MediaTrackEdited */ |
kMediaSetMediaTimeScaleSelect = 0x50A, /* MediaSetMediaTimeScale */ |
kMediaSetMovieTimeScaleSelect = 0x50B, /* MediaSetMovieTimeScale */ |
kMediaSetGWorldSelect = 0x50C, /* MediaSetGWorld */ |
kMediaSetDimensionsSelect = 0x50D, /* MediaSetDimensions */ |
kMediaSetClipSelect = 0x50E, /* MediaSetClip */ |
kMediaSetMatrixSelect = 0x50F, /* MediaSetMatrix */ |
kMediaGetTrackOpaqueSelect = 0x510, /* MediaGetTrackOpaque */ |
kMediaSetGraphicsModeSelect = 0x511, /* MediaSetGraphicsMode */ |
kMediaGetGraphicsModeSelect = 0x512, /* MediaGetGraphicsMode */ |
kMediaGSetVolumeSelect = 0x513, /* MediaGSetVolume */ |
kMediaSetSoundBalanceSelect = 0x514, /* MediaSetSoundBalance */ |
kMediaGetSoundBalanceSelect = 0x515, /* MediaGetSoundBalance */ |
kMediaGetNextBoundsChangeSelect = 0x516, /* MediaGetNextBoundsChange */ |
kMediaGetSrcRgnSelect = 0x517, /* MediaGetSrcRgn */ |
kMediaPrerollSelect = 0x518, /* MediaPreroll */ |
/* MediaSampleDescriptionChanged */ |
kMediaSampleDescriptionChangedSelect = 0x519, |
kMediaHasCharacteristicSelect = 0x51A /* MediaHasCharacteristic */ |
}; |
Media Video Parameters
The whichparam parameter to the MediaSetVideoParam and MediaGetVideoParam functions specifies which video parameter you want to adjust. QuickTime defines these constants that you can use to configure the whichparam parameter.
enum { |
kMediaVideoParamBrightness = 1, |
kMediaVideoParamContrast = 2, |
kMediaVideoParamHue = 3, |
kMediaVideoParamSharpness = 4, |
kMediaVideoParamSaturation = 5, |
kMediaVideoParamBlackLevel = 6, |
kMediaVideoParamWhiteLevel = 7 |
}; |
Term |
Definition |
|---|---|
|
The brightness value controls the overall brightness of the digitized video image. Brightness values range from 0 to 65,535, where 0 is the darkest possible setting and 65,535 is the lightest possible setting. |
|
The contrast value ranges from 0 to 65,535, where 0 represents no change to the basic image and larger values increase the contrast of the video image (that is, increase the slope of the transform). |
|
Hue is similar to the tint control on a television. It is specified in degrees with complementary colors set 180 degrees apart (red is 0 degrees, green is +120 degrees, and blue is -120 degrees). QuickTime supports hue values that range from 0 (-180 degrees shift in hue) to 65,535 (+179 degrees shift in hue), where 32,767 represents a 0 degrees shift in hue. |
|
The sharpness value ranges from 0 to 65,535, where 0 represents no sharpness filtering and 65,535 represents full sharpness filtering. Higher values result in a visual impression of increased picture sharpness |
|
The saturation value controls color intensity. For example, at high saturation levels, red appears to be red; at low saturation, red appears pink. Valid saturation values range from 0 to 65,535, where 0 is the minimum saturation value and 65,535 specifies maximum saturation. |
|
Black level refers to the degree of blackness in an image.The highest setting produces an all-black image; on the other hand, the lowest setting yields little, if any, black even with black objects in the scene. Black level values range from 0 to 65,535, where 0 represents the maximum black value and 65,535 represents the minimum black value. |
|
White level refers to the degree of whiteness in an image. White level values range from 0 to 65,535, where 0 represents the minimum white value and 65,535 represents the maximum white value |
Copyright © 2005, 2007 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2007-01-08