2.9 Version compatibility

It is possible to write plugins which dynamically make use of features of newer Hollywood versions. However, you need to be very careful when trying to access structure members or functions that are not available in all Hollywood versions. For example, let's consider the struct LoadSoundCtrl structure which looks like this:

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

You can see that the SubSong and NumSubSongs members are not available in Hollywood versions before 5.3 and Adapter is not available before Hollywood 6.0. This means that if your plugin is targetted at Hollywood 5.0 and up, you must only access these fields if you've verified that the user is running at least Hollywood 5.3 or 6.0 respectively. Otherwise you are going to access uninitialized memory which can easily lead to a crash. Hollywood will pass its version and revision numbers to your InitPlugin() function. It's recommended to store this information somewhere in your plugin so that your OpenStream() function can verify that the user is running Hollywood 5.3 or 6.0 before accessing the new structure members. Such a check could look like this:

 
ctrl->Frequency = 48000;
ctrl->Channels = 2;
ctrl->Bits = 16;
ctrl->Samples = numsamples;
ctrl->Flags = HWSNDFLAGS_SIGNEDINT;

// only return NumSubSongs if Hollywood >= 5.3
if(hwver > 5 || (hwver == 5 && hwrev >= 3)) {
    ctrl->NumSubSongs = numsubsongs;
}

Furthermore, be extra careful when using memset() to zero-out structure memory. For example, to zero-out struct LoadSoundCtrl you could do the following inside your OpenStream() implementation:

 
memset(ctrl, 0, sizeof(struct LoadSoundCtrl));

This, however, will cause memory access faults when the plugin is loaded by Hollywood versions older than version 6.0 because in that case the structure pointer passed to your OpenStream() function will point to a memory block that is smaller than the one used by Hollywood 6.0. If you just do a memset() without verifying version numbers first, you will write to unallocated memory which is likely to crash Hollywood. Thus, always make sure to check version numbers before reading from or writing to structure memory passed to your plugin by Hollywood.

If this is too much hassle for you, you can also declare that your plugin requires at least Hollywood 6.0 in your InitPlugin() implementation. If you do that, then you won't have to do all these checks of course because all Hollywood versions earlier than 6.0 will simply refuse to load your plugin.

You also have to be careful when calling Hollywood API functions from the different library bases. On its man page, every library base API function is followed by a version number in brackets which indicates the Hollywood version in which this API was first introduced. Before calling Hollywood API functions you must make sure that the user is running a Hollywood version that has this API using one of the methods described above.


Show TOC