Converts a picture into another image format using MIME types.

    GSErrCode ACAPI_Goodies (
        APIAny_ConvertMimePictureID,
        API_MimePicture*     mimePicture
    );

 

Parameters

mimePicture

[in/out] Parameters of the source and the destination picture.

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

The input parameters are not given correctly (see API_MimePicture)

APIERR_MEMFULL

Not enough memory to create the new pictHdl

For other common API errors see the API Errors document.

 

Remarks

This function is used to convert a picture from one standard image format to an other. The image formats are specified with MIME (Multi-purpose Internet Mail Extensions) types.

MIME types of the most commonly used image formats:

Windows Bitmap	image/x-bmp
GIF	image/gif
TIFF	image/tiff
JPEG	image/jpeg
Pict	image/pict
SGI	image/x-sgi
Photoshop Image	image/x-photoshop
PNG	image/png
MacPaint Image	image/x-macpaint
Truevision TGA	image/x-targa
QuickTime Image	image/x-quicktime

You can pass a special output type "vnd/DIB" to create a device independent bitmap on Windows, and "vnd/PICH" to create a PicHandle on Macintosh.

Conversion from one pixel depth to another is not supported at the moment.

You can use the APIAny_ConvertPictureID goody function for converting images with API_PictureFormat identifiers rather than MIME types.

Remember to dispose the returned outputHdl when it is not needed any more.

See more options at the description of the API_MimePicture structure.

 

Example

Converting a TIFF figure placed on the floorplan into a PNG format image:

GSErrCode ConvertPicture (const API_Guid& pictureGuid)
{
    API_Element element;
    BNZeroMemory (&element, sizeof (API_Element));
    element.header.guid = pictureGuid;

    GSErrCode   err = ACAPI_Element_Get (&element);
    if (err == NoError && element.picture.storageFormat == APIPictForm_TIFF) {
        API_ElementMemo memo;
        BNZeroMemory (&memo, sizeof (API_ElementMemo));
        err = ACAPI_Element_GetMemo (pictureGuid, &memo);
        if (err == NoError) {
            API_MimePicture mime;
            BNZeroMemory (&mime, sizeof (API_MimePicture));
            mime.mimeIn = "image/tiff";
            mime.inputHdl = memo.pictHdl;
            mime.mimeOut = "image/png";
            mime.inContainsMime = false;
            mime.outDepth = (API_ColorDepthID) -1;

            err = ACAPI_Goodies (APIAny_ConvertMimePictureID, &mime, nullptr);
            if (err == NoError) {
                /* mime.outputHdl contains the image in PNG format */

                /* change the figure, save into an image file, or anything else... */

                /* to avoid memory leak */
                BMKillHandle (&mime.outputHdl);
            }

            ACAPI_DisposeElemMemoHdls (&memo);
        }
    }

    return err;
}

See another sample for using MIME type image conversions in the DG_Test example project of the API DevKit.

 

Requirements

Version: API 5.1 or later

Header: APIdefs_Goodies.h

 

See Also

API_MimePicture
API_PictureFormat
APIAny_ConvertPictureID
ACAPI_Goodies
API Functions