Name
SaveSample -- save sample to disk (V5.0)
Synopsis
int ok = SaveSample(STRPTR filename, struct SaveSampleCtrl *ctrl);
Function
This function must save the sample provided by the pointer in the second parameter to the filename specified in the first parameter. Hollywood passes a pointer to a struct SaveSampleCtrl to this function. This structure looks like this:

 
struct SaveSampleCtrl
{
    APTR Data;                      // [in]
    int DataSize;                   // [in]
    int Samples;                    // [in]
    int Channels;                   // [in]
    int Bits;                       // [in]
    int Frequency;                  // [in]
    ULONG Flags;                    // [in]
    ULONG FormatID;                 // [in] -- V5.3
    STRPTR Adapter;                 // [in] -- V10.0
    struct hwUserTagList *UserTags; // [in] -- V10.0
};

In this structure Hollywood passes the following information to your SaveSample() function:

Data:
This contains the raw PCM data to save to the file.

DataSize:
This contains the size of the Data buffer in bytes.

Samples:
The total number of PCM frames to save. Note that this is specified in PCM frames, not in bytes.

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

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

Frequency:
The number of PCM frames that should be played per second.

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

HWSNDFLAGS_BIGENDIAN
The PCM samples are stored in big endian format. This flag is only meaningful if the bit resolution is 16.

HWSNDFLAGS_SIGNEDINT
The PCM samples are stored as signed integers. This is typically set for 16-bit samples.

FormatID:
This member contains the identifier of the sample format the file should be saved in. You only need to look at this member if your plugin supports more than one output sample format. But be careful, you are only allowed to look at this member if the user is running at least Hollywood 5.3. Otherwise, you must not access this member because older versions of Hollywood don't support it. (V5.3)

Adapter:
Starting with Hollywood 10.0 users can specify the file adapter that should be used to save a sample. If this member is non-NULL, Hollywood wants your plugin to use the file adapter specified in Adapter to save the sample. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to save the sample. Make sure to check for Hollywood 10.0 before trying to access this member because it isn't there in previous versions. See hw_FOpenExt for details. (V10.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)

This function has to return True if the sample has been successfully saved or False in case of an error.

Inputs
filename
path to a destination file
ctrl
pointer to a struct SaveSampleCtrl containing the sample to be saved
Results
ok
True or False indicating success or failure

Show TOC