APTR handle = LoadImage(STRPTR filename, struct LoadImageCtrl *ctrl);

This function also has to provide certain information about the image it has just loaded. This information has to be written to the struct LoadImageCtrl that is passed in the second parameter. This structure looks like this:

struct LoadImageCtrl { int Width; // [out] int Height; // [out] int LineWidth; // [out] int AlphaChannel; // [out] int ForceAlphaChannel; // [out] int Type; // [out] ULONG Flags; // [in/out] -- V5.3 int ScaleWidth; // [in] -- V5.3 int ScaleHeight; // [in] -- V5.3 int BaseWidth; // [out] -- V5.3 int BaseHeight; // [out] -- V5.3 ULONG ScaleMode; // [in] -- V5.3 STRPTR Adapter; // [in] -- V6.0 ULONG *Palette; // [unused] -- V9.0 ULONG TransPen; // [out] -- V9.0 int Depth; // [out] -- V9.0 struct hwUserTagList *UserTags; // [in] -- V10.0 };

Be careful when accessing above structure members: LoadImageCtrl has seen several revisions in Hollywood's history. Before accessing members that haven't been there in all Hollywood versions you must make sure that your plugin has been opened by a Hollywood version that has those members or you will access unallocated memory!

The following information has to be provided by LoadImage():

Type:

This must be set to either HWIMAGETYPE_RASTER or HWIMAGETYPE_VECTOR. If you set this to HWIMAGETYPE_VECTOR, Hollywood will call your TransformImage() function whenever it needs to transform the image. This allows you to do lossless transformation of the vector image. For images of type HWIMAGETYPE_RASTER, TransformImage() is never called. Instead, Hollywood does all transformations itself.

Width:

Must be set to the image width in pixels.

Height:

Must be set to the image height in pixels.

Depth:

Must be set to the image's bit depth. (V9.0)

LineWidth:

Must be set to the image modulo width in pixels. This is often the same as the image width.

AlphaChannel:

Must be set to True or False, depending on whether or not this image has an alpha channel.

ForceAlphaChannel:

If this is set to True, Hollywood will automatically create an alpha channel for all objects that load this image. For example, if the user calls LoadBrush() on your image but does not set the LoadAlpha tag to True, the brush will still get an alpha channel if you set ForceAlphaChannel to True.

Flags:

The following flags may be set by Hollywood:

HWIMGFLAGS_TRANSPARENCY:

This flag will be set whenever the user sets the LoadTransparency tag to True. If HWIMGFLAGS_LOADPALETTE is set as well (see below), you must return the pen that is transparent in the TransPen member of struct LoadImageCtrl. If HWIMGFLAGS_LOADPALETTE is not set, you have to write the image's transparency information to its alpha channel and set the ForceAlphaChannel member to True. See above for more information. (V6.0)

HWIMGFLAGS_LOADPALETTE:

This flag will be set whenever the user sets the LoadPalette tag to True. If this flag is set, your implementation of LoadImage() should fail in case the image does not have a palette. If it has a palette, you have to return that palette when Hollywood calls your GetImage() implementation. Note that palette images must always use HWIMAGETYPE_RASTER. They may not register as vector images. (V9.0)

The following flags may be set by your implementation:

HWIMGFLAGS_DIDSCALE:

If your plugin has scale-loaded this image, you have to set the HWIMGFLAGS_DIDSCALE flag here so that Hollywood knows that your plugin has loaded and scaled the image. See below for more information on scaled loading of images. (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 image. This means that you have to use hw_FOpenExt() instead of hw_FOpen() to open the image. 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)

TransPen:

If HWIMGFLAGS_LOADPALETTE and HWIMGFLAGS_TRANSPARENCY are set and the image has a transparent pen, set TransPen to the index of that transparent pen. Otherwise set this member to HWPEN_NONE. (V9.0)

Starting with Hollywood 5.3 LoadImage() also supports scaled loading of images. This is optional functionality and need not be supported by LoadImage(). If you want to support it, you have to look at the members ScaleWidth and ScaleHeight of the struct LoadImageCtrl pointer that is passed to LoadImage(). Warning! Make sure that you access these members only if you have checked that your plugin has been opened by version 5.3 or higher of Hollywood. Otherwise, these members won't be there and trying to access them will read from bad memory locations and give you back random values. So if you want to implement support for scaled loading of images, first check for Hollywood 5.3 and then take a look at the following members of the struct LoadImageCtrl:

ScaleWidth:

If Hollywood wants your plugin to scale the image while loading, this member will be set to either a positive or negative integer. A positive integer value specifies the desired width in pixels for this image while a negative integer value is to be interpreted as a percentage value specifying the desired scaling factor relative to the original image width, i.e. "-75" means that the image should be scaled to 75% of its original width. If ScaleWidth is 0, Hollywood doesn't want to have any scaling. (V5.3)

ScaleHeight:

This works in the same way as described above for ScaleWidth except that it deals with the image height. (V5.3)

ScaleMode:

Contains the ID of a scale mode. Currently, this can be either 0 for hard scaling or 1 for interpolated scaling using anti-aliasing. (V5.3)

BaseWidth:

If your plugin supports scaled loading, you need to set this member to the original width of the image. This is important because otherwise Hollywood won't know the original size of the image as the Width member needs to be set to the scaled width if you do scaling. (V5.3)

BaseHeight:

Same as BaseWidth but for the image height. (V5.3)

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 LoadImageCtrl for storing information about the image

handle

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