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

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

 
struct LoadSoundCtrl
{
    ULONG Samples;      // [out]
    int Channels;       // [out]
    int Bits;           // [out]
    int Frequency;      // [out]
    ULONG Flags;        // [out]
    int SubSong;        // [in]  -- V5.3
    int NumSubSongs;    // [out] -- V5.3
    STRPTR Adapter;     // [in]  -- V6.0
};

The following information has to be written to the struct LoadSoundCtrl pointer by OpenStream():

Samples:
The total number of PCM frames in the sound file. This can be 0 if you set the HWSNDFLAGS_INFINITE flag (see below).

Channels:
The number of channels used by the sound file. This must be either 1 (mono) or 2 (stereo).

Bits:
The number of bits per PCM sample. This must be either 8 or 16.

Frequency:
The number of PCM frames that should be played per second. Usually 44100 or 48000.

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

HWSNDFLAGS_BIGENDIAN
The PCM samples are stored in big endian format. This flag is only meaningful if the bit resolution is 16. This flag is unsupported on Windows, AROS x86, and Android.

HWSNDFLAGS_SIGNEDINT
The PCM samples are stored as signed integers. This flag must always be set for 16-bit samples. For 8-bit samples this flag is unsupported on Windows, Linux and Android, i.e. 8-bit samples must always be unsigned on these three platforms. On all other platforms this flag must be set for 8-bit samples and the samples must be signed.

HWSNDFLAGS_CANSEEK
Plugin supports seeking directly to PCM frames using SeekStream(). Note that even if this flag isn't set, your plugin still needs to be able to rewind the stream, i.e. seek it back to the very beginning when 0 is passed to SeekStream(). See SeekStream for details.

HWSNDFLAGS_INFINITE:
Set this flag to tell Hollywood that this stream will loop forever and will never finish. In that case you also have to set Samples to 0. (V9.0)

SubSong:
This member will be set by Hollywood to the sub-song within the sound file that Hollywood wants your plugin to open. Only useful for old tracker modules. (V5.3)

NumSubSongs:
This must be set by your plugin to the total number of sub-songs in the sound file. This is typically set to 1 because most sound file formats do not support sub-songs. This feature is only here to allow support for old tracker module formats that can have various sub-songs in the same file. (V5.3)

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 sound file. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to open the sound 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 LoadSoundCtrl for storing information about the sound file
Results
handle
a handle that identifies this sound file or NULL if plugin doesn't want to handle this sound file

Show TOC