Name
OpenVideo -- open a video file (V5.0)
Synopsis
APTR handle = OpenVideo(STRPTR filename, struct OpenVideoCtrl *ctrl);
Function
This function has to open the specified filename, check if it is in a video file format that the plugin wants to handle, and, if it is, return a handle to the video file back to Hollywood. Otherwise it has to return NULL. The handle returned by OpenVideo() is an opaque datatype that only your plugin knows about. Hollywood will simply pass this handle back to your NextPacket() function when it wants to have the individual packets of the video file.

This function also has to provide certain information about the video file it has just opened. This information has to be written to the struct OpenVideoCtrl that is passed in the second parameter. This structure looks like this:

 
struct OpenVideoCtrl
{
    int Width;         // [out]
    int Height;        // [out]
    ULONG Duration;    // [out]
    int Frequency;     // [out]
    int Channels;      // [out]
    int SeekMode;      // [out]
    int BitRate;       // [out]
    int PixFmt;        // [out]
    ULONG Flags;       // [out]
    int Pad;           // [unused]
    double FrameTime;  // [out]
    DOSINT64 FileSize; // [out] -- V6.0
    STRPTR Adapter;    // [in]  -- V6.0
};

The following information has to be written to the struct OpenVideoCtrl pointer by OpenVideo():

Width:
Frame width in pixels.

Height:
Frame height in pixels.

Duration:
Duration of the video stream in milliseconds.

Frequency:
The number of PCM frames that should be played per second. Usually 44100 or 48000. If there is no audio stream accompanying the video stream, set this to 0.

Channels:
The number of channels used by the sound file. This must be either 1 (mono) or 2 (stereo). If there is no audio stream accompanying the video stream, set this to 0.

SeekMode:
This member specifies the unit in which SeekVideo() receives its seek destination position. This can be one of the following constants:

HWVIDSEEKMODE_TIME:
Seek destination position will be passed as a time stamp in milliseconds. This is the most common seek mode but not all video formats support it.

HWVIDSEEKMODE_BYTE:
Seek destination position will be passed as an absolute position in bytes which is calculated by multiplying the BitRate parameter of this structure with the target time stamp. This will obviously only work with video streams that use a constant bit rate. If you choose this mode, make sure to set BitRate to the correct video bit rate.

Note that this member doesn't have any effect if the HWVIDFLAGS_CANSEEK flag isn't set.

BitRate:
Set this to the number of bytes this video stream needs to store one second of video data. You only need to provide this information if you've set SeekMode to HWVIDSEEKMODE_BYTE. Otherwise this information is not needed. Please note that in contrast to its name, this member actually needs to be set to a value in bytes, not in bits!

PixFmt:
This member specifies the pixel format in which you want to provide the individual video frame data to Hollywood. This can be one of the following constants:

HWVIDPIXFMT_YUV420P:
Pixel data is provided in planar YUV 4:2:0 format.

HWVIDPIXFMT_ARGB32:
Pixel data is provided as 32-bit ARGB pixel data.

Flags:
A combination of the following flags describing additional properties of the stream:

HWVIDFLAGS_CANSEEK
This plugin's SeekVideo() function supports seeking according to the mode specified in SeekMode. Note that even if this flag isn't set, your plugin still needs to be able to rewind the video stream, i.e. seek it back to the very beginning in case 0 is passed to SeekVideo(). See SeekVideo for details.

FrameTime:
Specifies how long each video frame should be presented in seconds which can then be used to compute the frame rate. For example, a FrameTime of 0.04 means that the video is meant to play at 25 frames per second.

FileSize:
If Hollywood 6.0 or higher is calling your function, you should set this member to the size of the video file in bytes or -1 if you don't know the size. Setting this member is optional but doing so allows Hollywood to open your video faster since Hollywood won't have to query the file size on its own if you can provide it. Make sure to check for Hollywood 6.0 before touching this member because it wasn't there in previous versions. (V6.0)

Adapter:
Starting with Hollywood 6.0 users can specify the file adapter that should be used to open certain files. If this member is non-NULL, Hollywood wants your plugin to use the file adapter specified in Adapter to open the video file. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to open the video file. Make sure to check for Hollywood 6.0 before trying to access this member because it isn't there in previous versions. See hw_FOpenExt for details. (V6.0)

Please note that you should not use ANSI C functions like fopen() to open the file that is passed to this function because the filename that is passed to this function can also be a specially formatted filename specification that Hollywood uses to load files that have been linked to applets or executables. In order to be able to load these files correctly, you have to use special IO functions provided by Hollywood. See File IO information for details.

Inputs
filename
filename to open
ctrl
pointer to a struct OpenVideoCtrl for storing information about the video file
Results
handle
a handle that identifies this video file or NULL if plugin doesn't want to handle this video file

Show TOC