Name
hw_LoadImage -- load image (V5.0)
Synopsis
APTR handle = hw_LoadImage(STRPTR filename, struct hwTagList *tags,
                  int *width, int *height, int *alpha);
Function
This function loads the specified image file and returns a handle to it. If this function succeeds, you can call hw_GetImageData() to get a pointer to the raw 32-bit pixel data of this image. See hw_GetImageData for details. On success, hw_LoadImage() will also return the image dimensions in pixels as well as a boolean value that indicates whether or not the image uses alpha channel transparency.

Note that hw_LoadImage() will load the pixel data as 32-bit RGBA bytes. If you want to have the pixel data in ARGB format, you have to explicitly request this by passing the respective tag (see below).

Also note that by default, hw_LoadImage() will only use Hollywood's inbuilt image loaders. Loaders provided by plugins or the host OS won't be used by default. You can change that by passing the HWLDIMGTAG_LOADER tag (see below). If you pass the string default in that tag, hw_LoadImage() will first ask plugin loaders, then inbuilt loaders, then OS native loaders to open the image. This is also the default loading order used by all Hollywood image loading functions.

The following tags are currently supported by hw_LoadImage():

HWLDIMGTAG_USEARGB:
If you set the iData member of this tag item to True, the pixel data will be returned in ARGB format. By default, RGBA order is used. (V6.1)

HWLDIMGTAG_SCALE:
This tag allows you to apply a scaling factor to the image. If you want to use this tag, set the pData member of this tag to a pointer to a double which contains the desired scaling factor. A scaling factor of 1.0, which is also the default, means no scaling, 2.0 means 200% scaling, and so on. (V8.0)

HWLDIMGTAG_INTERPOLATE:
If HWLDIMGTAG_SCALE is set to a scaling factor, this tag can be used to turn on bilinear interpolation for the scaling operation. Just set the iData member of the tag item to True and hw_LoadImage() will scale the image using bilinear interpolation. Defaults to False. (V8.0)

HWLDIMGTAG_LOADER:
This tag allows you to specify one or more loaders that should be asked to load the image. The pData member of this tag must be set to a string containing the name of at least one image loader or a special keyword (see the Hollywood documentation for more information). Multiple names or keywords must be separated by the vertical bar character (|). If this tag is set, hw_LoadImage() will fail in case the specified loaders refuse to handle the file. Note that this tag defaults to inbuilt which means that by default, only image loaders inbuilt into Hollywood will be asked to load the file. If you want plugins and host OS loaders to be asked as well, pass the string default here, for example, to use Hollywood's default loader order (plugins first, then inbuilt, then native, see the Hollywood documentation for details). (V9.0)

HWLDIMGTAG_ADAPTER:
This tag allows you to specify one or more file adapters that should be used to open the image. The pData member of this tag must be set to a string containing the name of at least one file adapter or a special keyword (see the Hollywood documentation for more information). Multiple names or keywords must be separated by the vertical bar character (|). If this tag is set, hw_LoadImage() will fail in case the specified file adapter refuses to open the file. (V9.0)

When you're done with the image, call hw_FreeImage() on it. See hw_FreeImage for details.

Designer compatibility
Supported since Designer 4.0

Inputs
file
image file to load
tags
additional options or NULL (see above)
width
pointer to an int that receives the image's width in pixels on success or NULL if you don't want this information
height
pointer to an int that receives the image's height in pixels on success or NULL if you don't want this information
alpha
pointer to an int that receives the image's alpha channel setting on success (either True or False) or NULL if you don't want this information
Results
handle
handle to the image if it was successfully loaded, else NULL

Show TOC