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