DVD Playback Framework Reference

DVD Playback is a core technology introduced in OS X version 10.3. Mac apps can use DVD Playback to display a DVD-Video recording located on an optical disc or a mass storage device such as a hard drive. DVD Playback makes it easy for applications to incorporate basic video playback features such as selecting a title from a menu and playing the title, as well as advanced features such as bookmarks, video clips, and multiple viewing angles.

Functions

Declaration

Swift

funcDVDInitialize() -> OSStatus

Objective-C

OSStatusDVDInitialize(void);

Return Value

A result code. If a new DVD-Video playback session is successfully initiated, this function returns noErr. If a session already exists, this function returns kDVDErrorInitializingLib. For other possible result codes, see DVD Playback Result Codes.

Discussion

When preparing to play a DVD, you must call this function to initialize a new DVD-Video playback session. Only one process at a time can use DVD Playback. When you are finished using DVD Playback, you should call the function DVDDispose to end the session.

Return Value

Discussion

This function registers a callback that you write to handle unrecoverable errors during video playback. You should call this function immediately after calling the function DVDInitialize. If you don’t register a callback to handle unrecoverable errors, your application may crash when a fatal error occurs. For information about how to write such a callback function, see DVDFatalErrCallBackFunctionPtr.

Return Value

Discussion

Before attempting to open a DVD-Video media folder, you should call this function to verify that the folder is valid. If another media folder is open, before calling this function you should call DVDCloseMediaFile or DVDCloseMediaVolume to close the other folder.

Declaration

Return Value

Discussion

This function closes a VIDEO_TS media folder that was previously opened using the function DVDOpenMediaFile. If necessary, this function stops playback before closing the folder. You must call this function before attempting to open another media folder.

Declaration

Return Value

Discussion

This function closes a VIDEO_TS media folder that was previously opened using the function DVDOpenMediaVolume. If necessary, this function stops playback before closing the folder. You must call this function before attempting to open another media folder.

Deprecation Statement

Declaration

Parameters

inDevice

A handle to the GDevice structure for the graphics device you want to use for video playback.

outSupported

A pointer to a Boolean variable. On return, a value of TRUE indicates that the specified graphics device can be used for DVD-Video playback. A value of FALSE indicates the device cannot be used for this purpose. If the value is FALSE, the device may require a different video driver than the one currently in use.

Parameters

Return Value

Discussion

You need to call this function or DVDSetVideoDisplay each time you move the video playback window to a new graphics device. To avoid degrading video performance, you should not attempt to draw a video playback window that spans two different devices.

Deprecation Statement

Declaration

Parameters

newDevice

A handle to the GDevice structure for the graphics device you want to use for video playback.

outSupported

A pointer to a Boolean variable. On return, a value of TRUE indicates that the specified graphics device can be used for DVD-Video playback. A value of FALSE indicates the device cannot be used for this purpose. If the value is FALSE, the current video playback device remains unchanged.

Return Value

A result code. If the specified device is not supported, this function returns an error and maintains the current device. See DVD Playback Result Codes.

Discussion

This convenience function is equivalent to calling the function DVDIsSupportedDevice followed by a call to DVDSetVideoDevice. This function works correctly even if there is no current video playback device.

Parameters

inDisplay

The Quartz display ID for the graphics display you want to use for video playback. For information about how to get a display ID, see Quartz Display Services Reference.

outSupported

A pointer to a Boolean variable. On return, a value of TRUE indicates that the specified graphics display can be used for DVD-Video playback. A value of FALSE indicates the display cannot be used for this purpose. If the value is FALSE, the display may require a different video driver than the one currently in use.

Return Value

Discussion

You need to call this function or DVDSetVideoDevice each time you move the video playback window to a new graphics display. To avoid degrading video performance, you should not attempt to draw a video playback window that spans two different displays.

Parameters

newDisplay

The Quartz display ID for the graphics display you want to use for video playback. For information about how to get a display ID, see Quartz Display Services Reference.

outSupported

A pointer to a Boolean variable. On return, a value of TRUE indicates that the specified graphics display can be used for DVD-Video playback. A value of FALSE indicates the display cannot be used for this purpose. If the value is FALSE, the current video playback display remains unchanged.

Return Value

A result code. If the new display is not supported, returns an error and maintains the current display. See DVD Playback Result Codes.

Discussion

This convenience function is equivalent to calling the function DVDIsSupportedDisplay followed by a call to DVDSetVideoDisplay. This function works correctly even if there is no current video playback display.

Return Value

Discussion

If you’re using a Carbon window for DVD-Video playback, you need to use this function in two situations:

After calling the function DVDInitialize to start a new DVD-Video playback session, you should call this function and pass the graphics port for the window.

When video is not playing and you want to draw into the area of the window you set by calling the function DVDSetVideoBounds, you should call this function and pass NULL in the inVidPort parameter. When you are finished drawing into the video area of the window and you are ready to resume video playback, you should call this function again and pass the window port in the inVidPort parameter.

Return Value

Discussion

If you’re using a Cocoa window for DVD-Video playback, you need to use this function in two different situations:

Immediately after calling the function DVDInitialize to start a new DVD-Video playback session, you should call this function and pass the window ID associated with the Cocoa window.

When video is not playing and you want to draw into the area of the window you set by calling the function DVDSetVideoBounds, you should call this function and pass NULL in the inVidWindowID parameter.

To learn how to obtain the window number for a Cocoa window, see the description of the windowNumber method in the NSWindow class.

Parameters

Return Value

Discussion

This function is used to set the area inside the current window in which to display the video. The video area is not required to fill the entire window. Generally you should set the video area to be smaller than the window whenever the aspect ratio of the current title and window are different. To find the aspect ratio of the current title, use the function DVDGetAspectRatio.

Because the aspect ratios of the titles in a DVD-Video media folder are not always the same, you may need to call this function repeatedly to reset the video area as the user makes different viewing choices.

Return Value

Discussion

The native dimensions of a title are specified by the author of the DVD-Video media. The width and height are typically 720 x 480 pixels for the NTSC video format and 720 x 576 pixels for the PAL video format.

Return Value

Discussion

The aspect ratio of the video can change whenever a different title or menu is displayed. You can use this function together with DVDGetNativeVideoSize to calculate the bounds of the video area in a window.

Parameters

Return Value

Discussion

DVD@ccess is a feature in Apple’s DVD Studio Pro that allows the DVD-Video author to embed external links to web-based resources and activate these links during video playback. Some users may find this feature to be intrusive, so DVD@ccess support is turned off by default.

Declaration

Return Value

Discussion

This function pauses the video playback and freezes the video. Before calling this function, DVD-Video media needs to be open and video playback started. After calling this function, the media is still considered to be in video playback mode—that is, you may call DVDStop without first calling DVDResume.

Declaration

Return Value

Discussion

If you call this function while a title is playing, video playback is stopped, the current video playback position is saved, and the video area is cleared to the color black.

If you call this function a second time with no intervening play commands, the video playback position is cleared and the playback position is now the beginning of the disc. This is equivalent to calling the function DVDClearLastPlayBookmark.

Return Value

Discussion

This function advances the media in the specified direction at the specified rate. When you scan at a rate other than kDVDScanRate1x (normal speed), the audio channel is muted and subtitles are not displayed. If the scan rate is normal and the direction is forward, this function is equivalent to DVDPlay. This function does not support video playback at normal speed in the reverse direction.

Return Value

Discussion

Before calling this function, the media needs to be open and video playback started. If the media is not paused when you call this function, this function pauses the media before stepping the frame in the forward direction.

You should also call this function if the user changes the display configuration or resolution during video playback. To learn how to receive a notification that the display configuration is about to change, see Quartz Display Services Reference.

Declaration

Return Value

Discussion

This function restores the video playback information saved by a previous call to the function DVDSleep. You should call this function whenever the operating system wakes up the machine and you have already called DVDSleep. To find out when the machine is waking up from sleep:

Cocoa applications can add an observer to the workspace notification center for the notification NSWorkspaceDidWakeNotification.

You should also call this function if the user changes the display configuration or resolution during video playback. To learn how to receive a notification that the display configuration has changed, see Quartz Display Services Reference.

Parameters

Return Value

Discussion

Before calling this function, DVD-Video media needs to be open and video playback started. Not every DVD has every menu type. If you attempt to jump to a non-existent menu, this function returns an error.

Declaration

Return Value

A result code. If no submenu is active, this function does nothing and returns . For other possible result codes, see DVD Playback Result Codes.

Discussion

This function is used to navigate one level up in a hierarchical structure in the same domain—for example, from a scene selection menu back to the main menu. This action is comparable to navigating upwards in the directory or folder hierarchy of a file system.

Return Value

Discussion

You should call this function whenever the user navigates between buttons in the menu using the keyboard. This function moves the focus to the button. If you pass in kDVDUserNavigationEnter, the button action is executed.

Return Value

Discussion

This function checks to see if a specified point lies inside one of the buttons in the current menu. If so, this function executes the button’s action and passes back its index. Note that the bounding rectangle of a button is not necessarily the same as the clickable area; not all buttons even have a clickable area. See also DVDDoButtonActivate.

Parameters

A pointer to an integer. On return, the integer contains the number of buttons in the current menu.

selectedButton

A pointer to an integer. On return, the integer contains the 1-based index of the selected button.

forcedActivateButton

A pointer to an integer. On return, the integer contains the index of the button whose action is performed when a specified period of time elapses after the menu is first displayed.

userButtonOffset

A pointer to an integer. On return, the integer contains the index of the first user-selectable button. If the number of user-selectable buttons in a menu is smaller than the total number of buttons, this index may be greater than zero.

numberOfUserButtons

A pointer to an integer. On return, the integer contains the number of user-selectable buttons in the current menu.

Parameters

The zero-based index of a menu button. If your button index is 1-based, you should decrement the index before you pass it to this function.

outRect

A pointer to a Quartz rectangle. On return, the rectangle contains the position and dimensions of the specified button in window local coordinates.

autoAction

A pointer to an integer flag. On return, a value of 1 indicates the button is a forced activate button—that is, the button’s action is executed immediately when the button is selected. A value of 0 indicates the button is not a forced activate button.

Parameters

Return Value

Discussion

This function passes back a 64-bit identifier that can help you distinguish between different media folders. While the identifiers generated by this function are not guaranteed to be unique (see below), duplicate identifiers are extremely rare.

There are two known limitations of this function:

Two copies of the same DVD that are produced at different times do not necessarily have the same identifier. This can happen when the two media folders have minor differences.

Two different DVDs with similar content—collections of episodes from a television series, for example—do not always have different identifiers. This can happen when the two media folders are identical.

Return Value

Discussion

This function passes back the media volume name as a Core Foundation string. This is the name seen on the desktop when OS X mounts a DVD-Video disc. For information about using Core Foundation strings, see CFString Reference.

Parameters

Return Value

Discussion

This function defines the specified chapter to be the current video playback chapter. If video playback is paused, this function starts playing the chapter immediately. Note that some discs do not allow jumping directly to a chapter.

Declaration

Return Value

Discussion

Before calling this function, DVD-Video media needs to be open and video playback started. This function finds and begins to play the previous chapter. If there is no previous chapter, this function rewinds to the beginning of the current chapter and begins playing.

Declaration

Return Value

Discussion

Before calling this function, DVD-Video media needs to be open and video playback started. This function finds and begins to play the next chapter. If there is no next chapter, this function continues playing the current chapter.

Return Value

Discussion

Before calling this function, DVD-Video media needs to be open and video playback started. The DVD-Video author decides how many camera angles are used. If the specified angle does not exist, this function does nothing.

Declaration

Parameters

outStreamNum

A pointer to an integer. On return, the integer contains the identifier of the current subpicture stream, or 0 if the current title has no subpictures. DVD-Video media supports up to 32 subpicture streams per title.

Parameters

inCode

A constant that specifies the default language for the specified subpicture extension. For a list of possible values, see Language Codes. If no language is specified—that is, if you pass in kDVDLanguageNoPreference or kDVDLanguageCodeNone—the default subpicture language code is matched to the language setting in the International Preferences Panel.

Parameters

inCode

A constant that specifies the default audio language for the specified audio extension.. For a list of possible values, see Language Codes. If no language is specified—that is, if you pass in kDVDLanguageNoPreference or kDVDLanguageCodeNone—the default audio language is matched to the language setting in the International Preferences Panel.

Declaration

Parameters

inCode

An integer code that specifies the default menu language for the current title. For a list of possible values, see Language Codes. If no language is specified—that is, if you pass in kDVDLanguageNoPreference or kDVDLanguageCodeNone—the default menu language is matched to the language setting in the International Preferences Panel.

Parameters

A generic pointer to memory for a bookmark in your calling program, or NULL. On return, this memory contains the new bookmark.

The size of this memory should be equal to or greater than the actual size of a bookmark in bytes. To determine the actual size of a bookmark, see the Discussion below.

ioBookmarkDataSize

On entry, a pointer to an integer that contains the size of your bookmark memory. If you haven’t allocated memory for a bookmark, set this size to zero. On return, the integer’s value is the actual size of a new bookmark. See the Discussion below.

Return Value

Discussion

This function is used when playing media on a DVD-Video disc. Before calling this function, the media needs to be open and playing. This function passes back a bookmark to the current play position in the current DVD-Video playback session.

To request a play bookmark, you need to call this function twice. The first call determines the minimum required size for the bookmark:

UInt32size=0;

DVDGetBookmark(NULL,&size);

After you allocate sufficient memory for the bookmark, call this function again to create the bookmark, passing it the location and size of your bookmark memory:

Return Value

Discussion

This function is used when playing media on a DVD-Video disc. Before calling this function, the media needs to be open. This function uses the specified bookmark to set the video playback position, and begins playing the media. See also DVDSetLastPlayBookmark.

Parameters

A generic pointer to memory for a bookmark in your calling program, or NULL. On return, this memory contains the last bookmark after the first Stop command.

The size of this memory should be equal to or greater than the actual size of a bookmark in bytes. To determine the actual size of a bookmark, see the discussion below.

ioBookmarkDataSize

On entry, a pointer to an integer that contains the size of your bookmark memory. If you haven’t allocated memory for a bookmark, set this size to zero. On return, the integer’s value is the actual size of a new bookmark. See the Discussion below.

Parameters

Return Value

Discussion

This function is used when playing media on a DVD-Video disc. Before calling this function, the media needs to be open. This function uses the specified bookmark to set the video playback position, but does not begin playing the media. See also DVDGotoBookmark.

Declaration

Return Value

Discussion

This function sets the video playback position to the beginning of the disc, but does not begin playing the media. Calling this function is equivalent to calling the function DVDStop twice in succession. Before calling this function, media needs to be open.

Return Value

Discussion

This function passes back the region codes assigned to the DVD-Video disc that’s currently in use. Before calling this function, you need to call the function DVDOpenMediaVolume to open the media folder on the disc.

To test whether a disc is authorized for playback in region n, you need to compute the bitwise AND of outCode with region code n. If the result is equal to region code n, the disc is authorized for playback in region n. For example, this source code shows how to test whether a disc is authorized for playback in region 1:

Parameters

outCode

A pointer to a DVDRegionCode variable. On return, the variable specifies the region code that’s assigned to the DVD drive currently in use. If the drive was never initialized, the region code is kDVDRegionCodeUninitialized. For more information about region codes, see Region Codes.

outNumberChangesLeft

A pointer to an integer. On return, the integer contains the number of region code changes remaining for this drive.

Return Value

Discussion

This function passes back the region code assigned to the DVD drive that’s currently in use. Before calling this function, you need to call the function DVDOpenMediaVolume to open the media folder on a disc that’s mounted in the drive.

To test whether region n is assigned to a drive, you need to compute the bitwise AND of outCode with region code n. If the result is equal to region code n, the drive can play discs that are authorized for playback in region n. For example, this source code shows how to test whether region 1 is assigned to a drive:

Return Value

Discussion

In order to play a DVD-Video disc in a DVD drive, the region code assigned to the drive must match one of the region codes assigned to the disc. The region code assigned to a DVD drive may be changed a total of five times, after which the drive’s region is permanently locked. The initial region code assigned to a new drive is set automatically when the user inserts a disc for the first time.

You can use the function DVDGetDiscRegionCode to retrieve the region codes on a disc; you can use the function DVDGetDriveRegionCode to retrieve the region code assigned to a drive and the number of remaining changes. If there is a mismatch and the number of remaining changes is greater than zero, you should display a dialog that asks whether the user wants to reset the drive region to match one of the disc regions. If the user wants to proceed, you should obtain an authorization object and call this function.

Return Value

Discussion

This function is optional. You may register more than one callback, and you may register multiple events for a single callback. For every call to this function, there should be a corresponding call to the function DVDUnregisterEventCallBack using the identifier for this registration. You should unregister your callbacks before calling the function DVDDispose to end the current DVD-Video playback session.

Parameters

Return Value

Discussion

This function should be called once for each call to the function DVDRegisterEventCallBack. You should unregister all event callbacks before calling the function DVDDispose to end the current DVD-Video playback session.

Parameters

Return Value

Discussion

The default interval between DVD Playback time events is 900 milliseconds. You can use this function to lengthen or shorten the interval between time events. This function is relevant when you have used the function DVDRegisterEventCallBack to register a callback for one or both of the time events: kDVDEventTitleTime and kDVDEventChapterTime . Time event callbacks are typically used for tasks such as updating the elapsed time or remaining time displayed in your user interface.

Return Value

Discussion

This function passes back the volume name of the current media as a C string. This is the name seen on the desktop when OS X mounts a DVD-Video disc.

Special Considerations

This function has a serious limitation: it does not support volume names with multiple byte characters. For this reason, applications running in OS X version 10.4 or later should use the replacement function DVDGetMediaVolumeCFName instead.

Declaration

Parameters

A code that identifies the event. For a list of event codes, see Event Codes.

inEventValue1

The first event-specific parameter value. For a list of one or both parameters associated with each event, see Event Codes.

inEventValue2

The second event-specific parameter value. For a list of one or both parameters associated with each event, see Event Codes.

inRefCon

Optional application-defined data. This is the same data you pass in when you register the callback using the function DVDRegisterEventCallBack.

Discussion

Your callback function is called from a different thread than the main application thread. You should not attempt to draw inside this function. Instead, cache any necessary information and do the actual drawing when you are back in the main thread for your application.

If your callback function is registered for multiple events, the function is called separately for each different event.

Parameters

Optional application-defined data. This is the same data that you pass in when you register this callback using the function DVDSetFatalErrorCallBack.

Discussion

When an unrecoverable error occurs, the DVD-Video playback session cannot continue and your callback function is invoked to handle the error. Your function should report the fatal error to the user, perform any necessary cleanup, and call the function DVDDispose.

Discussion

These constants are used along with the scan direction to specify the speed and direction of play. The constant kDVDScanRate1x represents the normal playback speed; the slower and faster playback speeds are multiples of the normal speed. See the functions DVDScan and DVDGetScanRate.

Discussion

A DVD Playback region code is a bitfield in which a zero in bit n is used to specify region n. The bits are numbered from right to left, and only the least significant 8 bits are used. For example, the region code 11101111 or 0xef specifies region 5. A region code can also specify more than one region; the region code 11110110 or 0xf6, for example, specifies regions 1 and 4.

Most DVD drives are designed to play only those discs that are authorized for use in a specific region. Region codes are used to:

Discussion

Table 1 lists the constants you use to register a callback function as an event handler for one or more DVD playback events. To learn how to register an event handler, see the function DVDRegisterEventCallBack.

Unlike Carbon events, you do not need to call a function to retrieve the data associated with a playback event. When your event callback is invoked, the associated data is contained in one or both event value parameters. For more information, see DVDEventCallBackFunctionPtr.