APTR handle = OpenVideo(STRPTR filename, struct OpenVideoCtrl *ctrl);

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 struct hwUserTagList *UserTags; // [in] -- V10.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)

UserTags:

This member will be set to a list of user tags in case they were specified in the Hollywood script. User tags are a way of passing additional information from Hollywood scripts to plugin functions. Note that even if your plugin doesn't support any user tags, you should still look for this tag and pass the user tags to hw_FOpenExt because the user tags passed in UserTags could also be intended for another plugin, namely the file adapter plugin passed in Adapter. See User tags for details. Make sure to check for Hollywood 10.0 before trying to access this member because it isn't there in previous versions. (V10.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.

filename

filename to open

ctrl

pointer to a struct OpenVideoCtrl for storing information about the video file

handle

a handle that identifies this video file or NULL if plugin doesn't want to handle this video file