API Guide Home (Online version only) |

# ImageLib.h File Reference

## Detailed Description

Public 68k include file for the Imaging Library.

This file contains routines for capturing, storing, iterating, resizing, and manipulating images. The imaging library is a client of both the camera driver and the JPEG library.

Definition in file ImageLib.h.

Include dependency graph for ImageLib.h:

Go to the source code of this file.

## Functions

- Err ImageLibOpen (UInt16 libRef)
- Err ImageLibClose (UInt16 libRef)
- Err ImageLibGetVersion (UInt16 libRef, UInt32 *dwVerP)
- Err ImageLibCameraExists (UInt16 libRef, Boolean *existsP)
- Err ImageLibImageCapture (UInt16 libRef, Boolean fullsize, Boolean playShutterSound, Boolean drawImmediately, Coord x, Coord y, UInt16 *newRecNoP)
- Err ImageLibImageSave (UInt16 libRef, UInt16 recIndex, const char *name, UInt16 category)
- BitmapType * ImageLibPreviewBitmapCreate (UInt16 libRef, Err *errP)
- Err ImageLibPreviewBitmapFill (UInt16 libRef, BitmapType *imageP)
- Err ImageLibPreviewDraw (UInt16 libRef, Coord x, Coord y)
- BitmapType * ImageLibImageBitmapCreate (UInt16 libRef, UInt16 recIndex, Err *errP)
- Err ImageLibImageBitmapFill (UInt16 libRef, UInt16 recIndex, BitmapType *imageP)
- Err ImageLibImageDraw (UInt16 libRef, UInt16 recIndex, Coord x, Coord y)
- BitmapType * ImageLibThumbnailBitmapCreate (UInt16 libRef, UInt16 recIndex, Err *errP)
- Err ImageLibThumbnailBitmapFill (UInt16 libRef, UInt16 recIndex, BitmapType *imageP)
- Err ImageLibThumbnailDraw (UInt16 libRef, UInt16 recIndex, Coord x, Coord y)
- Err ImageLibBitmapDelete (UInt16 libRef, BitmapType *bmp)
- Err ImageLibDeleteImage (UInt16 libRef, UInt16 recIndex)
- Err ImageLibResizeImage (UInt16 libRef, UInt16 recIndex)
- Err ImageLibGetImageDatabases (UInt16 libRef, DmOpenRef *dbMainP, DmOpenRef *dbNoteP, DmOpenRef *dbImageP)
- Err ImageLibGetImageInfo (UInt16 libRef, UInt16 recIndex, Char *name, Boolean *fullSizeP, UInt32 *createdP, UInt32 *sizeP, UInt16 *categoryP, Char *categoryName, Boolean *lockedP, UInt32 *uidP)
- Err ImageLibSetImageInfo (UInt16 libRef, UInt16 recIndex, const char *name, UInt16 *categoryP)
- Err ImageLibCopyImageToVFS (UInt16 libRef, UInt16 recIndex, UInt16 volRefNum, const char *fileName)
- Err ImageLibCopyImageFromVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, const char *name, UInt16 category, UInt16 *newRecIndexP)
- BitmapType * ImageLibImageBitmapCreateFromVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, Err *errP)
- Err ImageLibImageBitmapFillFromVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, BitmapType *imageP)
- Err ImageLibImageDrawFromVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, Coord x, Coord y)
- BitmapType * ImageLibThumbnailBitmapCreateFromVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, Err *errP)
- Err ImageLibThumbnailBitmapFillFromVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, BitmapType *imageP)
- Err ImageLibThumbnailDrawFromVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, Coord x, Coord y)
- Err ImageLibDoAttachImageDialog (UInt16 libRef, UInt16 *recIndexP, UInt16 *volRefNumP, char *fileName, UInt16 initialCategory, Boolean showConfirmation, Boolean internalImagesOnly, const char *dialogTitle, const char *btnTitle)
- Err ImageLibCopyImageToBuffer (UInt16 libRef, UInt16 recIndex, MemPtr bufP)
- Err ImageLibCopyImageToFile (UInt16 libRef, UInt16 recIndex, FileHand fileH)
- Err ImageLibInsertImageFromBuffer (UInt16 libRef, MemPtr bufP, UInt32 size, const char *name, UInt16 category, UInt16 *newRecIndexP)
- Err ImageLibInsertImageFromFile (UInt16 libRef, FileHand fileH, const char *name, UInt16 category, UInt16 *newRecIndexP)
- ImageIteratorHandle ImageLibIterateImages (UInt16 libRef, UInt16 category, UInt16 sortType, UInt16 *imageCountP, Err *errP)
- ImageIteratorHandle ImageLibIterateVFSImages (UInt16 libRef, UInt16 volRefNum, const char *path, Boolean recurseBelow, UInt16 sortType, UInt16 *imageCount, Err *errP)
- Err ImageLibIterSort (UInt16 libRef, ImageIteratorHandle iter, UInt16 sortType)
- Err ImageLibIterGetImageInfo (UInt16 libRef, ImageIteratorHandle iter, UInt16 index, char *name, UInt16 nameLen, UInt16 *categoryP, UInt16 *recIndexP, UInt16 *volRefNumP, UInt32 *createdP, UInt32 *sizeP, char *path, UInt16 pathLen, Boolean *lockedP)
- Err ImagelibIterGetCount (UInt16 libRef, ImageIteratorHandle iter, UInt16 *imageCountP)
- Err ImageLibIterDeleteImage (UInt16 libRef, ImageIteratorHandle iter, UInt16 index)
- Err ImageLibIterRemoveImage (UInt16 libRef, ImageIteratorHandle iter, UInt16 index)
- Err ImageLibIterFree (UInt16 libRef, ImageIteratorHandle iter)
- Err ImageLibIterDrawImage (UInt16 libRef, ImageIteratorHandle iter, UInt16 index, Coord x, Coord y)
- Err ImageLibIterDrawThumbnail (UInt16 libRef, ImageIteratorHandle iter, UInt16 index, Coord x, Coord y)
- Err ImageLibIterSearch (UInt16 libRef, ImageIteratorHandle iterH, const char *name, Boolean partialMatch, UInt16 *index)
- void ImageLibSetProgressCallback (UInt16 libRef, ImageLibProgressCallbackType callback)
- Err ImageLibCopyImage (UInt16 libRef, UInt16 recIndex, const char *newName, UInt16 *newRecIndexP)
- Err ImageLibFindImageByID (UInt16 libRef, UInt32 uniqueID, UInt16 *recIndexP)
- Err ImageLibPreviewStart (UInt16 libRef, void *windowH, Coord x, Coord y)
- Err ImageLibPreviewStop (UInt16 libRef)
- Err ImageLibDrawJPEG (UInt16 libRef, MemPtr jpegDataP, UInt32 jpegSize, Coord left, Coord top, Boolean fitToScreen, Coord width, Coord height)
- Err ImageLibTurnCameraOff (UInt16 libRef)
- Err ImageLibSetImageID (UInt16 libRef, UInt16 recIndex, const char *mediaIDP, const char *containerIDP)
- Err ImageLibGetImageID (UInt16 libRef, UInt16 recIndex, char *mediaIDP, char *containerIDP)
- Err ImageLibGetDimensions (UInt16 libRef, UInt16 recIndex, Coord *width, Coord *height, Boolean fitToDimensions)
- Err ImageLibGetDimensionsVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, Coord *width, Coord *height, Boolean fitToDimensions)
- Err ImageLibIterGetDimensions (UInt16 libRef, ImageIteratorHandle iter, UInt16 index, Coord *width, Coord *height, Boolean fitToDimensions)
- Err ImageLibGetDimensionsJPEG (UInt16 libRef, MemPtr jpegDataP, UInt32 jpegSize, Coord *width, Coord *height, Boolean fitToDimensions)
- Err ImageLibResize (UInt16 libRef, UInt16 recIndex, Coord *widthP, Coord *heightP, Boolean maintainAspectRatio)
- Err ImageLibResizeVFS (UInt16 libRef, UInt16 volRefNum, const char *fileName, Coord *widthP, Coord *heightP, Boolean maintainAspectRatio)
- Err ImageLibIterResize (UInt16 libRef, ImageIteratorHandle iter, UInt16 index, Coord *widthP, Coord *heightP, Boolean maintainAspectRatio)
- Err ImageLibResizeJPEG (UInt16 libRef, MemPtr jpegInputP, UInt32 inputSize, Coord *widthP, Coord *heightP, Boolean maintainAspectRatio, MemPtr *outputPP, UInt32 *outputSizeP)
- Err ImageLibIterRefresh (UInt16 libRef, ImageIteratorHandle iter, UInt16 index, const char *newVFSName)
- Err ImageLibSetJPEGQuality (UInt16 libRef, Int32 value)
- Int32 ImageLibGetJPEGQuality (UInt16 libRef)
- Err ImageLibLockImage (UInt16 libRef, UInt16 recIndex)
- Int32 ImageLibGetAveragePictureSize (UInt16 libRef, Boolean fullsize)
- void ImageLibCheckLockedImages (UInt16 libRef, const Char *phoneNumber)

## Function Documentation

Err ImageLibBitmapDelete | ( | UInt16 | libRef,
|  | BitmapType * | bmp |
| ) |  |  |

Deletes a bitmap created by the library.

Use ImageLibBitmapDelete to delete any bitmap that was created and returned by the imaging library (ImageLibPreviewBitmapCreate, ImageLibImageBitmapCreate and ImageLibThumbnailBitmapCreate).

Parameters:

  | libRef,: | IN: Library reference number.
  | bmp,: | IN: Bitmap to delete.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibCameraExists | ( | UInt16 | libRef,
|  | Boolean * | existsP |
| ) |  |  |

Detects presence of camera driver.

The imaging library loads the camera driver dynamically. If the driver was found and was loaded successfully, ImageLibCameraExists writes true to existsP, otherwise it writes false.

This routine will attempt to load the camera driver if it hasn't already been loaded. The driver will remain loaded until the imaging library is unloaded, or until ImageLibTurnCameraOff is called.

See also:
  ImageLibTurnCameraOff

Parameters:

  | libRef,: | IN: Library reference number.
  | existsP,: | OUT: true if camera successfully loaded. Otherwise false.

Return values:

  | Err | 0 on success or error code on failure.

void ImageLibCheckLockedImages | ( | UInt16 | libRef,
|  | const Char * | phoneNumber |
| ) |  |  |

Verifies the locked images match the given phone number. If they don't, all locked images are purged from the database.

Parameters:

  | libRef,: | IN: Library reference number.
  | phoneNumber,: | IN: String containing the phone number to verify against.

Err ImageLibClose | ( | UInt16 | libRef | ) |

Library close function for 68k clients of the library. This routine maps to the sysLibTrapClose trap.

This function is an empty stub (see comments for ImageLibOpen). All library cleanup is done from PilotMain.

This function is not available to ARM clients of the library.

See also:
  ImageLibOpen

Parameters:

  | libRef,: | IN: Library reference number.

Return values:

  | Err | 0 on success or error code on failure.

Err ImageLibCopyImage | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | const char * | newName,
|  | UInt16 * | newRecIndexP |
| ) |  |  |

Creates a copy of an image in the database.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of the image to copy.
  | newName,: | IN: Name of the newly copied image.
  | newRecIndexP,: | OUT: Index of the newly copied image. Pass NULL if you don't care about this value.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibCopyImageFromVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | const char * | name,
|  | UInt16 | category,
|  | UInt16 * | newRecIndexP |
| ) |  |  |

Copies an image from a VFS volume to the database.

volRefNum should be obtained via a call to VFSVolumeEnumerate

If a picture with a matching name and category already exists in the database, that image is not overwritten. After the call, there will be two images with the same name and category.

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture001.jpg")
  | name,: | IN: Name of the image in the database (ie "picture001")
  | category,: | IN: Category that the image should be assigned to
  | newRecIndexP,: | OUT: Record index of the newly stored picture. Pass NULL if you don't care what the new index is.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibCopyImageToBuffer | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | MemPtr | bufP |
| ) |  |  |

Copies a JPEG from the image database to a chunk of memory at bufP. The allocated memory block must be large enough to hold the entire blob of JPEG data. The size of the JPEG can be determined with ImageLibGetImageInfo.

Fullsize images may requires that bufP be larger than 64 kB. Use FtrPtrNew or MemChunkNew to create buffers larger than 64 kB. Otherwise, consider using ImageLibCopyImageToFile instead.

See also:
  ImageLibGetImageInfo

  ImageLibCopyImageToFile

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of the picture
  | bufP,: | IN,OUT: Pointer to the block of memory that should receive the image.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibCopyImageToFile | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | FileHand | fileH |
| ) |  |  |

Copies a JPEG from the image database to a Palm OS file stream. The library writes to the file stream at its current postion. When done, the library leaves the file handle pointing to the end of the file. To see the jpeg data, the file handle should be rewound to its original location.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of the picture
  | fileH,: | IN: Handle to an open file stream.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibCopyImageToVFS | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | UInt16 | volRefNum,
|  | const char * | fileName |
| ) |  |  |

Copies an image from the database to a VFS volume.

Copies an image from the database to a VFS volume, overwriting any previous file that existed on the volume with the same name.

volRefNum should be obtained via a call to VFSVolumeEnumerate

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of the picture
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture.jpg")

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibDeleteImage | ( | UInt16 | libRef,
|  | UInt16 | recIndex |
| ) |  |  |

Delete a picture from the database.

This routine deletes an image and its thumbnail from the database.

Deleting a picture invalidates the record indices of all subsequent images in the database. Records are deleted with DmRemoveRecord. They are not archived.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: index of image to delete.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibDoAttachImageDialog | ( | UInt16 | libRef,
|  | UInt16 * | recIndexP,
|  | UInt16 * | volRefNumP,
|  | char * | fileName,
|  | UInt16 | initialCategory,
|  | Boolean | showConfirmation,
|  | Boolean | internalImagesOnly,
|  | const char * | dialogTitle,
|  | const char * | btnTitle |
| ) |  |  |

Displays the attach image dialog.

Displays the attach image dialog. Allows to user to select a picture from a list. After choosing an image, the selection is written to the output parameters recIndexP, volRefNum, and filename.

If the user cancels the dialog, the return value is still 0. The values in recIndexP and volRefNumP indicate that the dialog was cancelled.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndexP,: | OUT: If the user selects an image from the database, recIndexP will contain the index of the image. If the user selects an image from a VFS volume, or they cancel the dialog, or an error occurs, recIndexP will contain kInvalidRecIndex.
  | volRefNumP,: | OUT: If the user selects an image from the VFS system, volRefNumP will contain the volume ref number of the selected image. In all other cases, volRefNumP will contain vfsInvalidVolRef.
  | fileName,: | OUT: If the user selects an image from the VFS system, the full path of the file will be copied into fileNameP. fileName should be capable of holding the largest possible VFS filename. If the user does not select a VFS file, fileName[0] will be NULL.
  | initialCategory,: | IN: The initial category that should be highlighted in the category dropdown. Pass 0 for unfiled. Pass dmAllCategories to show all pictures from the database.
  | showConfirmation,: | IN: If true, a confirmation dialog will be displayed that shows the image in full size. If false, the confirmation dialog is skipped.
  | internalImagesOnly,: | IN: If true, images from VFS volumes are not displayed to the user.
  | dialogTitle,: | IN: The string to display as the title of the dialog. Pass null to display a localized default.
  | btnTitle,: | IN: The string to display as the title of the OK button. Pass null to display a localized default.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibDrawJPEG | ( | UInt16 | libRef,
|  | MemPtr | jpegDataP,
|  | UInt32 | jpegSize,
|  | Coord | left,
|  | Coord | top,
|  | Boolean | fitToScreen,
|  | Coord | width,
|  | Coord | height |
| ) |  |  |

Decompresses a blob of JPEG data and draws it to the current draw window. The picture is drawn at left,top, which are relative to the draw window.

If the image needs to be resized, its aspect ratio is maintained. To determine how an image will be resized beforehand, call ImageLibGetDimensionsJPEG.

See also:
  ImageLibGetDimensionsJPEG

Parameters:

  | libRef,: | IN: Library reference number.
  | jpegDataP,: | IN: Pointer to a JPEG image in memory.
  | jpegSize,: | IN: Size of the source image in bytes.
  | left,: | IN: x location to draw the image, relative to the current draw window.
  | top,: | IN: y location to draw the image, relative to the current draw window.
  | fitToScreen,: | IN: If true, the JPEG is resized to fit in a box defined by width and height. If false, image is not resized.
  | width,: | IN: Max width of drawn image. Ignored if fitToScreen is false.
  | height,: | IN: Max height of drawn image. Ignored if fitToScreen is false.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibFindImageByID | ( | UInt16 | libRef,
|  | UInt32 | uniqueID,
|  | UInt16 * | recIndexP |
| ) |  |  |

Determines the record index of an image in the database given a unique ID. The image is found by calling DmFindRecordByID on the main database.

If you need to store a permanent reference to a picture in the database, it is best to store its unique ID. You can obtain the unique ID of an image by calling ImageLibGetImageInfo. To access an image by unique ID, call ImageLibFindImageByID to retrieve the record index, and then use the record index to access the picture.

See also:
  ImageLibGetImageInfo

Parameters:

  | libRef,: | IN: Library reference number.
  | uniqueID,: | IN: Unique ID of the image to find.
  | recIndexP,: | OUT: Record index of the image.

Return values:

  | Err | 0 on success, non-zero on error.

Int32 ImageLibGetAveragePictureSize | ( | UInt16 | libRef,
|  | Boolean | fullsize |
| ) |  |  |

Returns the average size that a picture will be at the current compression factor.

Parameters:

  | libRef,: | IN: Library reference number.
  | fullsize,: | IN: True to return average of last 20 fullsize captures. False to return average of palm size captures.

Return values:

  | Int32 | 0 Average size.

Err ImageLibGetDimensions | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | Coord * | width,
|  | Coord * | height,
|  | Boolean | fitToDimensions |
| ) |  |  |

Retrieves the dimensions of an image in the database.

This routine allows clients of the library to query the dimensions of an image in the database. If fitToDimensions is false, the routine copies the full dimensions of the image to widthP and heightP. The initial values of widthP and heightP are ignored. If fitToDimensions is true, the routine calculates how big the image will be after it is downsized to fit in a box determined by the initial values of widthP and heightP.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of image.
  | width,: | IN,OUT: On output, contains the width of the image. On input, if fitToDimensions is true, determines the max width that the image should be.
  | height,: | IN,OUT: On output, contains the height of the image. On input, if fitToDimensions is true, determines the max height that the image should be.
  | fitToDimensions,: | IN: If true, tells the library to return the dimensions that an image would be if it was forced to draw in a box bounded by widthP and heightP.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibGetDimensionsJPEG | ( | UInt16 | libRef,
|  | MemPtr | jpegDataP,
|  | UInt32 | jpegSize,
|  | Coord * | width,
|  | Coord * | height,
|  | Boolean | fitToDimensions |
| ) |  |  |

Retrieves the dimensions of a blob of JPEG data in memory.

This routine allows clients of the library to query the dimensions of an arbitrary blob of JPEG data. The routine follows the same semantics as ImageLibGetDimensions.

See also:
  ImageLibGetDimensions

Parameters:

  | libRef,: | IN: Library reference number.
  | jpegDataP,: | IN: Pointer to a JPEG image in memory.
  | jpegSize,: | IN: Size of the source image in bytes.
  | width,: | IN,OUT: On output, contains the width of the image. On input, if fitToDimensions is true, determines the max width that the image should be.
  | height,: | IN,OUT: On output, contains the height of the image. On input, if fitToDimensions is true, determines the max height that the image should be.
  | fitToDimensions,: | IN: If true, tells the library to return the dimensions that an image would be if it was forced to draw in a box bounded by widthP and heightP.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibGetDimensionsVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | Coord * | width,
|  | Coord * | height,
|  | Boolean | fitToDimensions |
| ) |  |  |

Retrieves the dimensions of an image on a VFS volume.

This routine allows clients of the library to query the dimensions of an image that resides on a VFS volume. The routine follows the same semantics as ImageLibGetDimensions.

See also:
  ImageLibGetDimensions

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture.jpg")
  | width,: | IN,OUT: On output, contains the width of the image. On input, if fitToDimensions is true, determines the max width that the image should be.
  | height,: | IN,OUT: On output, contains the height of the image. On input, if fitToDimensions is true, determines the max height that the image should be.
  | fitToDimensions,: | IN: If true, tells the library to return the dimensions that an image would be if it was forced to draw in a box bounded by widthP and heightP.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibGetImageDatabases | ( | UInt16 | libRef,
|  | DmOpenRef * | dbMainP,
|  | DmOpenRef * | dbNoteP,
|  | DmOpenRef * | dbImageP |
| ) |  |  |

Return the references to the database that are used to store pictures.

The image library opens each database when it is loaded, and closes them when it is unloaded. Do not close the database references that are returned by this function because the references are still being used by the imaging library.

The data in each database is stored in little endian format.

The main database contains one record for each image in the database. Each record has a fixed size and contains information about the picture. The image database contains the actual JPEG data for each image. The main database acts as a master table and the images database is a child table.

The notes database is not currently used.

The category of an image is determined by the category of its record in the main database. Categories are not used in the image table.

Parameters:

  | libRef,: | IN: Library reference number.
  | dbMainP,: | OUT: Reference to the main database. Pass NULL for this parameter if you don’t want to retrieve it.
  | dbNoteP,: | OUT: Reference to the note database. Pass NULL for this parameter if you don’t want to retrieve it.
  | dbImageP,: | OUT: Reference to the images database.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibGetImageID | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | char * | mediaIDP,
|  | char * | containerIDP |
| ) |  |  |

Gets the media and container IDs for an image in the database.

The media ID and container ID should both be at least 21 bytes in size. The library copies 21 bytes to the supplied buffers.

See also:
  ImageLibSetImageID

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of image.
  | mediaIDP,: | IN: Media ID.
  | containerIDP,: | IN: Container ID.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibGetImageInfo | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | Char * | name,
|  | Boolean * | fullSizeP,
|  | UInt32 * | createdP,
|  | UInt32 * | sizeP,
|  | UInt16 * | categoryP,
|  | Char * | categoryName,
|  | Boolean * | lockedP,
|  | UInt32 * | uidP |
| ) |  |  |

Retrieves information about an image stored in the database.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of the picture
  | name,: | OUT: Buffer to receive the name of the image. The buffer should be at least 32 characters long (31 + null terminator). Pass NULL for this parameter if you don't want to retrieve it.
  | fullSizeP,: | OUT: true if image is 640x480, false if palm size. Pass NULL for this parameter if you don't want to retrieve it.
  | createdP,: | OUT: Timestamp when picture was creatd. Pass NULL for this parameter if you don't want to retrieve it.
  | sizeP,: | OUT: Size of the image data in bytes. Pass NULL for this parameter if you don't want to retrieve it.
  | categoryP,: | OUT: Category that that picture is assigned to. Pass NULL for this parameter if you don't want to retrieve it.
  | categoryName,: | OUT: Text description of the picture's category (ie 'Unfiled'). Pass NULL for this parameter if you don't want to retrieve it.
  | lockedP,: | OUT: true if image is locked.
  | uidP,: | OUT: Unique ID of the image.

Return values:

  | Err | 0 on success, non-zero on error.

Int32 ImageLibGetJPEGQuality | ( | UInt16 | libRef | ) |

Returns the compression factor used for JPEG compression operations.

Parameters:

  | libRef,: | IN: Library reference number.

Return values:

  | Int32 | Compression value. [1,99]

Err ImageLibGetVersion | ( | UInt16 | libRef,
|  | UInt32 * | dwVerP |
| ) |  |  |

Retrieves the version number of the image library.

Parameters:

  | libRef,: | IN: Library reference number.
  | dwVerP,: | OUT: Pointer to library version variable.

Return values:

  | Err | 0 on success or error code on failure.

BitmapType* ImageLibImageBitmapCreate | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | Err * | errP |
| ) |  |  |

Creates a 16 bit bitmap for holding an image from the database. If recIndex is a valid image index, that image is loaded into the resulting bitmap. Otherwise, the result is an empty picture.

When called from a 68k application, the return value should be treated as opaque. The bitmap can safely be passed to the Palm OS bitmap routines, but 68k applications should not attempt to dereference members of the bitmap structure directly.

Bitmaps created with this function should be disposed of by calling ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.

If an error occurs, this function returns NULL and writes an error code to errP. If the function returns a non-NULL bitmap value, then *errP will always be 0.

If recIndex is kInvalidRecIndex, the result is an empty 160x120 bitmap. If recIndex is not kInvalidRecIndex, the result is a bitmap that contains the given image from the database. The returned bitmap will be 160x120 if the image in the database is 160x120, 320x240, 640x480, or any other image larger than 160x120 with a 4:3 aspect ratio. If the image has a non-standard size, it is downsized to fit in a 160x120 box. The aspect ratio of the picture is preserved. Images that are less than 160x120 are not scaled at all.

See also:
  ImageLibBitmapDelete

  ImageLibPreviewStop

  ImageLibPreviewStart

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of image to fill bitmap with. Use kInvalidRecIndex to create an empty 160x120, 16 bit bitmap.
  | errP,: | OUT: If the function succeeds, 0 is written to errP. Otherwise, a non-zero error code is written. This parameter should not be NULL.

Return values:

  | BitmapType* | On success, the result is a new bitmap with a bit depth of 16. On error, the result is NULL.

BitmapType* ImageLibImageBitmapCreateFromVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | Err * | errP |
| ) |  |  |

Creates a 16 bit bitmap for holding an image from a VFS volume. The library decompresses the image from the volume and stores it in the result.

When called from a 68k application, the return value should be treated as opaque. The bitmap can safely be passed to the Palm OS bitmap routines, but 68k applications should not attempt to dereference members of the bitmap structure directly.

Bitmaps created with this function should be disposed of by calling ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.

If an error occurs, this function returns NULL and writes an error code to errP. If the function returns a non-NULL bitmap value, then *errP will always be 0.

The picture is always resized to fit in a 160x120 box. If the image needs to be resized, its aspect ratio is maintained.

See also:
  ImageLibBitmapDelete

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture.jpg")
  | errP,: | OUT: If the function succeeds, 0 is written to errP. Otherwise, a non-zero error code is written. This parameter should not be NULL.

Return values:

  | BitmapType* | On success, the result is a new bitmap with a bit depth of 16. On error, the result is NULL.

Err ImageLibImageBitmapFill | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | BitmapType * | imageP |
| ) |  |  |

Fills a bitmap with an image from the database.

The imageP argument should represent a bitmap created with ImageLibImageBitmapCreate.

The image from the database is resampled as necessary to fit the dimensions of imageP. When the image is a jpeg, the DCT scaling features of the IJG library are used to get the image size close to the destination size. From there, the image is resampled with a filter to match the dimensions of imageP. If the aspect ratio of imageP does not match the aspect ratio of the picture, the picture is stretched to fit.

See also:
  ImageLibImageBitmapCreate

  ImageLibBitmapDelete

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: index of image to fill bitmap with.
  | imageP,: | IN,OUT: Bitmap to fill.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibImageBitmapFillFromVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | BitmapType * | imageP |
| ) |  |  |

Fills a 16 bit bitmap with an image from a VFS volume. The library decompresses the image from the volume and stores it in the supplied bitmap. The image is resized to fit the dimensions of the supplied bitmap.

The imageP argument should represent a bitmap created with ImageLibImageBitmapCreate or ImageLibImageBitmapCreateFromVFS.

The image is resampled as necessary to fit the dimensions of imageP. When the image is a jpeg, the DCT scaling features of the IJG library are used to get the image size close to the destination size. From there, the image is resampled with a filter to match the dimensions of imageP. If the aspect ratio of imageP does not match the aspect ratio of the picture, the picture is stretched to fit.

See also:
  ImageLibImageBitmapCreate

  ImageLibImageBitmapCreateFromVFS

  ImageLibBitmapDelete

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture001.jpg")
  | imageP,: | IN,OUT: Bitmap to fill.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibImageCapture | ( | UInt16 | libRef,
|  | Boolean | fullsize,
|  | Boolean | playShutterSound,
|  | Boolean | drawImmediately,
|  | Coord | x,
|  | Coord | y,
|  | UInt16 * | newRecNoP |
| ) |  |  |

Captures an image and stores it in the database.

Images are appended to the end of the database.

The camera driver always captures 640x480 images. If fullSize is false, the data from the camera is downsampled to 160x120 using a filtering algorithm.

Captures are currently done in 16 bit RGB mode. Capturing an image requires at least 600 kB of free space in the dynamic heap (640x480x2).

Captured pictures are stored in uncompressed palmOS bitmap format. To compress an image as a JPEG, call ImageLibImageSave.

See also:
  ImageLibImageSave

Parameters:

  | libRef,: | IN: Library reference number.
  | fullsize,: | IN: true capture a 640x480 image. false to capture 160x120
  | playShutterSound,: | IN: true to play a camera shutter sound.
  | drawImmediately,: | IN: true to immediately draw the captured image to the current draw window.
  | x,: | IN: x location to draw the captured image. Relative to the current draw window. Ignored if drawImmediately is false.
  | y,: | IN: y location to draw the captured image. Relative to the current draw window. Ignored if drawImmediately is false.
  | newRecNoP,: | OUT: index of the new image. If the capture fails, kInvalidRecIndex is written to this value. Pass NULL if you don’t care what the new index is.

Return values:

  | Err | 0 on success or error code on failure.

Err ImageLibImageDraw | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | Coord | x,
|  | Coord | y |
| ) |  |  |

Draws an image from the database to the current draw window.

Draws an image from the database to the current draw window at x,y. x and y are window relative coordinates.

If necessary, the image is downsized to fit in a 160x120 box. The aspect ratio of the picture is preserved.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: index of image to draw.
  | x,: | IN: x location to draw the preview image, relative to the current draw window.
  | y,: | IN: y location to draw the preview image, relative to the current draw window.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibImageDrawFromVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | Coord | x,
|  | Coord | y |
| ) |  |  |

Draws an image from from a VFS volume to the current draw window at x,y. x and y are window relative coordinates.

If necessary, the image is downsized to fit in a 160x120 box. The aspect ratio of the picture is preserved.

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture001.jpg")
  | x,: | IN: x location to draw the image, relative to the current draw window.
  | y,: | IN: y location to draw the image, relative to the current draw window.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibImageSave | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | const char * | name,
|  | UInt16 | category |
| ) |  |  |

Compresses a captured image to JPEG format.

Compresses a captured image to JPEG, sets the image name, and sets the category of the picture. After saving, the uncompressed bitmap data is discarded and replaced with the JPEG version of the image.

This routine should only be invoke on newly captured images, and it should only be called once per picture.

See also:
  ImageLibImageCapture

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of the image to compress.
  | name,: | IN: Name of the picture
  | category,: | IN: Category to store the image in

Return values:

  | Err | 0 on success or error code on failure.

Err ImageLibInsertImageFromBuffer | ( | UInt16 | libRef,
|  | MemPtr | bufP,
|  | UInt32 | size,
|  | const char * | name,
|  | UInt16 | category,
|  | UInt16 * | newRecIndexP |
| ) |  |  |

Inserts a JPEG blob into the image database, storing it with the supplied name and category.

Parameters:

  | libRef,: | IN: Library reference number.
  | bufP,: | IN: Pointer to a JPEG image in memory.
  | size,: | IN: Size of the source image in bytes.
  | name,: | IN: Name of the new image (ie "Picture001")
  | category,: | IN: The category to store the image in. Pass 0 for unfiled.
  | newRecIndexP,: | OUT: Index of the newly created image. Pass NULL if you don’t care about this value.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibInsertImageFromFile | ( | UInt16 | libRef,
|  | FileHand | fileH,
|  | const char * | name,
|  | UInt16 | category,
|  | UInt16 * | newRecIndexP |
| ) |  |  |

Insert an image into the database from a Palm OS file stream. The file stream is read from its current position to the end of the stream. When the routine is finished, it leaves the stream open and performs a FileSeek back to the original position.

Parameters:

  | libRef,: | IN: Library reference number.
  | fileH,: | IN: Handle to an open file stream that contains a JPEG starting at its current position.
  | name,: | IN: Name of the new image (ie "Picture001")
  | category,: | IN: The category to store the image in. Pass 0 for unfiled.
  | newRecIndexP,: | OUT: Index of the newly created image. Pass NULL if you don’t care about this value.

Return values:

  | Err | 0 on success, non-zero on error.

ImageIteratorHandle ImageLibIterateImages | ( | UInt16 | libRef,
|  | UInt16 | category,
|  | UInt16 | sortType,
|  | UInt16 * | imageCountP,
|  | Err * | errP |
| ) |  |  |

Creates an iterator for working with a collection of images in the database. When finished, the iterator refers to a data structure that contains images The iterator can be used to step through images, draw images, sort images, and search for images by name.

The returned iterator handle can be passed to other iterator routines that take an iterator handle. The handle should be freed by calling ImageLibIterFree.

See also:
  ImageLibIterFree

Parameters:

  | libRef,: | IN: Library reference number.
  | category,: | IN: The category to search. Pass 0 for unfiled. Pass dmAllCategories to iterate through all images in the databse.
  | sortType,: | IN: Initial sort order of the datastructure (kNoSortOrder, kSortByName, or kSortByDate)
  | imageCountP,: | OUT: Number of images in the iterator data structure. Pass NULL if you don't care about this value.
  | errP,: | OUT: 0 on success, non-zero on error. This parameter should not be null.

Return values:

  | ImageIteratorHandle | Opaque iterator handle.

ImageIteratorHandle ImageLibIterateVFSImages | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | path,
|  | Boolean | recurseBelow,
|  | UInt16 | sortType,
|  | UInt16 * | imageCount,
|  | Err * | errP |
| ) |  |  |

Creates an iterator for working with a collection of images on a VFS volume. When finished, the iterator refers to a data structure that contains images. The iterator can be used to step through images, draw images, sort images, and search for images by name.

The returned iterator handle can be passed to other iterator routines that take an iterator handle. The handle should be freed by calling ImageLibIterFree.

See also:
  ImageLibIterFree

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: VFS volume to search.
  | path,: | IN: Directory to start searching in.
  | recurseBelow,: | IN: true to recurse in all subdirectories of path. false to search in path only.
  | sortType,: | IN: Initial sort order of the datastructure (kNoSortOrder, kSortByName, or kSortByDate)
  | imageCount,: | OUT: Number of images in the iterator data structure. Pass NULL if you don't care about this value.
  | errP,: | OUT: 0 on success, non-zero on error. This parameter should not be null.

Return values:

  | ImageIteratorHandle | Opaque iterator handle.

Err ImageLibIterDeleteImage | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | index |
| ) |  |  |

Deletes an image (either from the database or from a VFS volume)

Permanently deletes an image given a reference to the image in an iterator. Given an iterator and an index to an image in the iterator, this routine determines whether the image resides in the internal database or on a VFS volume. If it resides on a VFS volume, the routine attempts to delete it by calling VFSFileDelete. If it is an internal image, the picture is nuked by calling ImageLibDeleteImage. After the image is deleted, it is removed from the iterator chain. All subsequent images in the iterator data structure move down one spot. The count of images in the iterator chain is decremented by one.

The iterator handle should be created with ImageLibIterateImages or ImageLibIterateVFSImages.

Deleting an image invalidates the iterator index for all subsequent images in the iterator chain. If you need to delete a range of images in an iterator, it is best to loop from back to front.

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.
  | index,: | IN: Index of the image to delete. This is an index into the iterator, not an index to the image database.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterDrawImage | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | index,
|  | Coord | x,
|  | Coord | y |
| ) |  |  |

Draws an image in an iterator chain to the current draw window at x,y. x and y are window relative coordinates.

If the image resides in the internal database, this routine calls ImageLibImageDraw to draw it. If it is a VFS image the call is dispatched to ImageLibImageDrawFromVFS

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.
  | index,: | IN: Index of the image to draw. This is an index into the iterator, not an index to the image database.
  | x,: | IN: x location to draw the preview image, relative to the current draw window.
  | y,: | IN: y location to draw the preview image, relative to the current draw window.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterDrawThumbnail | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | index,
|  | Coord | x,
|  | Coord | y |
| ) |  |  |

Draws a thumbnail for an image in an iterator chain to the current draw window at x,y. x and y are window relative coordinates.

If the image resides in the internal database, this routine calls ImageLibThumbnailDraw to draw it. If it is a VFS image the call is dispatched to ImageLibThumbnailDrawFromVFS

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.
  | index,: | IN: Index of the image to draw. This is an index into the iterator, not an index to the image database.
  | x,: | IN: x location to draw the preview image, relative to the current draw window.
  | y,: | IN: y location to draw the preview image, relative to the current draw window.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterFree | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter |
| ) |  |  |

Frees the memory associated with an iterator chain.

The iterator handle should be created with ImageLibIterateImages or ImageLibIterateVFSImages.

Once the iterator has been freed, it should not be used anymore.

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImagelibIterGetCount | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 * | imageCountP |
| ) |  |  |

Retrieves the number of images stored in the iterator data structure.

The iterator handle should be created with ImageLibIterateImages or ImageLibIterateVFSImages.

Iterator routines that take an index should ensure that the index is less than the value returned in imageCountP.

See also:
  ImageLibIterateImages

  ImageLibIterateVFSImages

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.
  | imageCountP,: | OUT: Number of images in the iterator data structure.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterGetDimensions | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | index,
|  | Coord * | width,
|  | Coord * | height,
|  | Boolean | fitToDimensions |
| ) |  |  |

Retrieves the dimensions of an image in an iterator chain.

This routine allows clients of the library to query the dimensions of an image in an iterator chain. The routine follows the same semantics as ImageLibGetDimensions.

See also:
  ImageLibGetDimensions

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Iterator handle
  | index,: | IN: Index of the image in the iterator. [0,imageCount)
  | width,: | IN,OUT: On output, contains the width of the image. On input, if fitToDimensions is true, determines the max width that the image should be.
  | height,: | IN,OUT: On output, contains the height of the image. On input, if fitToDimensions is true, determines the max height that the image should be.
  | fitToDimensions,: | IN: If true, tells the library to return the dimensions that an image would be if it was forced to draw in a box bounded by widthP and heightP.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterGetImageInfo | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | index,
|  | char * | name,
|  | UInt16 | nameLen,
|  | UInt16 * | categoryP,
|  | UInt16 * | recIndexP,
|  | UInt16 * | volRefNumP,
|  | UInt32 * | createdP,
|  | UInt32 * | sizeP,
|  | char * | path,
|  | UInt16 | pathLen,
|  | Boolean * | lockedP |
| ) |  |  |

Retrieves information about a single image in an iterator chain.

The iterator handle should be created with ImageLibIterateImages or ImageLibIterateVFSImages.

Pass NULL for any OUT parameter that you don't care about.

See also:
  ImageLibIterateImages

  ImageLibIterateVFSImages

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.
  | index,: | IN: Index of the image in the iterator. [0,imageCount)
  | name,: | OUT: Buffer to receive the name of the image. For VFS images, this is the full path and filename of the image (ie "/dcim/picture001.jpg"). For internal images, this is the name of the picture (ie "Picture001")
  | nameLen,: | IN: Size in bytes of the name buffer.
  | categoryP,: | OUT: Category of the picture if it is stored in the image database. 0xFF if it is a VFS picture.
  | recIndexP,: | OUT: Record index of the picture if it is stored in the image database. kInvalidRecIndex if it is a VFS picture.
  | volRefNumP,: | OUT: VFS volume ref number of the picture if it is stored on a VFS volume. vfsInvalidVolRef if it is stored in the internal database.
  | createdP,: | OUT: Timestamp when picture was creatd. Pass NULL for this parameter if you don't want to retrieve it.
  | sizeP,: | OUT: Size of the image data in bytes. Pass NULL for this parameter if you don't want to retrieve it.
  | path,: | OUT: Directory that the picture is stored in if it is a VFS image (ie /DCIM). Empty string if it is an internal image.
  | pathLen,: | IN: Size in bytes of the path buffer.
  | lockedP,: | OUT: true if the image is locked. False otherwise. VFS images are never locked.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterRefresh | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | index,
|  | const char * | newVFSName |
| ) |  |  |

Refreshes the information for an image in an iterator chain. If the image is stored in the image database, this routine updates the name, recIndex, category, size, timestamp, and locked status of the image. If it is a VFS picture, this routine updates the timestamp and size of the picture.

Call this function when an iterator refers to an image that has changed since the iterator was created. For example, if you downsize or resize an iternal image, call ImageLibIterRefresh to update the iterator information for that image.

If you rename a VFS picture that is referenced by an iterator chain, you can pass its new name for the newVFSName argument. Pass the full path and filename of the image. If you pass a string for this argument, the name of file in the iterator chain will be updated. Pass NULL for the newVFSName parameter if the iterator image refers to an internal picture or a VFS picture that whose name has not been changed (If you don't know what this is about, pass NULL).

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.
  | index,: | IN: Index of the image in the iterator. [0,imageCount)
  | newVFSName,: | IN: If picture is a VFS file, pass its new name for this parameters

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterRemoveImage | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | index |
| ) |  |  |

Removes an image from an iterator chain without deleting it from its original location.

Removes an image from an iterator chain without deleting it from its original location. Once an image is removed, it can no longer be accessed via the iterator. However, the image is still accessible from its original location (either in the image database or on a VFS card).

The iterator handle should be created with ImageLibIterateImages or ImageLibIterateVFSImages.

Removing an image invalidates the iterator index for all subsequent images in the iterator chain. If you need to remove a range of images in an iterator, it is best to loop from back to front.

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.
  | index,: | IN: Index of the image to remove. This is an index into the iterator, not an index to the image database.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterResize | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | index,
|  | Coord * | widthP,
|  | Coord * | heightP,
|  | Boolean | maintainAspectRatio |
| ) |  |  |

Resizes an image in an iterator chain.

This routine resizes an image in an iterator chain to any size. The routine follows the same semantics as ImageLibResize.

See also:
  ImageLibResize

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Iterator handle
  | index,: | IN: Index of the image in the iterator. [0,imageCount)
  | widthP,: | IN/OUT: On output, contains the new width of the image. On input, if maintainAspectRatio is true, determines the max width that the image should be. If maintainAspectRatio is false, determines the exact width that the image should be after resizing.
  | heightP,: | IN/OUT: On output, contains the new width of the image. On input, if maintainAspectRatio is true, determines the max width that the image should be. If maintainAspectRatio is false, determines the exact width that the image should be after resizing.
  | maintainAspectRatio,: | IN: If true, tells the library to maintain the aspect ratio of the image. In this case, the input values of widthP and heightP serve as maximum guidelines. If false, the image is stretched to fit the input values of widthP and heightP. the dimensions that an image would be if it was forced to draw in a box bounded by widthP and heightP.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterSearch | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iterH,
|  | const char * | name,
|  | Boolean | partialMatch,
|  | UInt16 * | index |
| ) |  |  |

Searches for an image in an iterator chain by name. To match, a picture's name must the name string starting in the first character. If partical match is true, then the entire string must match. Case is ignored for all comparisons. Pattern matching and wildcards are not supported.

Parameters:

  | libRef,: | IN: Library reference number.
  | iterH,: | IN: Handle to an iterator.
  | name,: | IN: String to search for.
  | partialMatch,: | IN: If true, only the beginning of a picture name must match. If false, the entire name must match.
  | index,: | OUT: Contains the index of the first picture that matches the search string. kInvalidRecIndex if no match found.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibIterSort | ( | UInt16 | libRef,
|  | ImageIteratorHandle | iter,
|  | UInt16 | sortType |
| ) |  |  |

Sorts the images in an iterator chain. Note that this only reorganizes images in the iterator data structure. This does not alter the way images are stored in the database or on a card. images, sort images, and search for images by name.

The iterator handle should be created with ImageLibIterateImages or ImageLibIterateVFSImages.

See also:
  ImageLibIterateImages

  ImageLibIterateVFSImages

Parameters:

  | libRef,: | IN: Library reference number.
  | iter,: | IN: Handle to an iterator.
  | sortType,: | IN: New sort order of the datastructure (kNoSortOrder, kSortByName, kSortByDate, kSortByNameDesc, or kSortByDateDesc)

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibLockImage | ( | UInt16 | libRef,
|  | UInt16 | recIndex |
| ) |  |  |

Returns the compression factor used for JPEG compression operations.

Once an image is locked, it is locked forever and can't be unlocked.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of the image to compress.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibOpen | ( | UInt16 | libRef | ) |

Library open call for 68k clients of the library. This routine maps to the sysLibTrapOpen trap.

It is customary for shared libraries to provide open and close functions. The open and close functions in ImageLib are empty stubs that exist for the sole purpose of adhering to past convention. This function does nothing and will always return errNone. All library initialization is done from PilotMain.

This function is not available to ARM clients of the library.

Parameters:

  | libRef,: | IN: Library reference number.

Return values:

  | Err | 0 on success or error code on failure.

BitmapType* ImageLibPreviewBitmapCreate | ( | UInt16 | libRef,
|  | Err * | errP |
| ) |  |  |

Creates a preview bitmap. If Compresses a captured image to JPEG, sets the image name, and sets the category of the picture. After saving, the uncompressed bitmap data is discarded and replaced with the JPEG version of the image.

When called from a 68k application, the return value should be treated as opaque. The bitmap can safely be passed to the Palm OS bitmap routines, but 68k applications should not attempt to dereference members of the bitmap structure directly.

Bitmaps created with this function should be disposed of by calling ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.

If an error occurs, this function returns NULL and writes an error code to errP. If the function returns a non-NULL bitmap value, then *errP will always be 0.

This function does not perform an image preview. The resulting bitmap is empty. To fill the bitmap with a preview image, pass it to ImageLibPreviewBitmapFill.

See also:
  ImageLibPreviewBitmapFill

  ImageLibBitmapDelete

Parameters:

  | libRef,: | IN: Library reference number.
  | errP,: | OUT: 0 on success, non-zero on error. This parameter should not be null.

Return values:

  | BitmapType | On success, the result is a new 160x120 bitmap whose bit depth matches the bit depth of the screen. On failure, the result is NULL

Err ImageLibPreviewBitmapFill | ( | UInt16 | libRef,
|  | BitmapType * | imageP |
| ) |  |  |

Fills a bitmap with a preview image from the camera.

The imageP argument should represent a bitmap created with ImageLibPreviewBitmapCreate.

See also:
  ImageLibPreviewBitmapCreate

  ImageLibBitmapDelete

  ImageLibPreviewStop

  ImageLibPreviewStart

Parameters:

  | libRef,: | IN: Library reference number.
  | imageP,: | IN,OUT: Bitmap to fill with a preview.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibPreviewDraw | ( | UInt16 | libRef,
|  | Coord | x,
|  | Coord | y |
| ) |  |  |

Draws a preview image to the current draw window.

Snaps a preview image with the camera driver and then draws it to the current draw window at x,y. x and y are relative coordinates.

See also:
  ImageLibPreviewStop

  ImageLibPreviewStart

Parameters:

  | libRef,: | IN: Library reference number.
  | x,: | IN: x location to draw the preview image, relative to the current draw window.
  | y,: | IN: y location to draw the preview image, relative to the current draw window.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibPreviewStart | ( | UInt16 | libRef,
|  | void * | windowH,
|  | Coord | x,
|  | Coord | y |
| ) |  |  |

Turns on the direct draw preview mode of the camera.

This routine serves as a front end to the camera driver's CameraLibPreviewStart function. After being called, the camera will display preview images to the supplied window at the given coordinates.

See also:
  ImageLibPreviewStop

Parameters:

  | libRef,: | IN: Library reference number.
  | windowH,: | IN: Window handle where preview images should be drawn. This should generally be a screen window.
  | x,: | IN: x location to draw the preview image. Relative to windowH.
  | y,: | IN: y location to draw the preview image. Relative to windowH.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibPreviewStop | ( | UInt16 | libRef | ) |

Turns off the direct draw preview mode of the camera.

This routine serves as a front end to the camera driver's CameraLibPreviewStop function. It halts previews that were initiated by a call to ImageLibPreviewStart.

See also:
  ImageLibPreviewStart

Parameters:

  | libRef,: | IN: Library reference number.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibResize | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | Coord * | widthP,
|  | Coord * | heightP,
|  | Boolean | maintainAspectRatio |
| ) |  |  |

Resizes an image in the database to any arbitrary size.

This routine resizes an image in the database to any size. The routine can maintain the existing aspect ratio of the image, or it can stretch it to fit any size.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of image.
  | widthP,: | IN,OUT: On output, contains the new width of the image. On input, if maintainAspectRatio is true, determines the max width that the image should be. If maintainAspectRatio is false, determines the exact width that the image should be after resizing.
  | heightP,: | IN,OUT: On output, contains the new width of the image. On input, if maintainAspectRatio is true, determines the max width that the image should be. If maintainAspectRatio is false, determines the exact width that the image should be after resizing.
  | maintainAspectRatio,: | IN: If true, tells the library to maintain the aspect ratio of the image. In this case, the input values of widthP and heightP serve as maximum guidelines. If false, the image is stretched to fit the input values of widthP and heightP. the dimensions that an image would be if it was forced to draw in a box bounded by widthP and heightP.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibResizeImage | ( | UInt16 | libRef,
|  | UInt16 | recIndex |
| ) |  |  |

Deprecated:

Resizes a fullsize picture in the database to 160x120 (palm size). The original fullsize image is replaced with the palm size version.

If the original image is a full size 640x480 jpeg, the image is downsampled using the DCT scaling features of the IJG library. This means that the JPEG is decompressed directly to 160x120, and then compressed again and saved back to the database.

If the original image is not a 640x480 jpeg, it is scaled as much as possible using the IJG scaling features. After decompression, the picture is resampled with a filter to get its dimensions to 160x120.

ImageLibResizeImage is deprecated. Use ImageLibResize instead.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: index of image to resize.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibResizeJPEG | ( | UInt16 | libRef,
|  | MemPtr | jpegInputP,
|  | UInt32 | inputSize,
|  | Coord * | widthP,
|  | Coord * | heightP,
|  | Boolean | maintainAspectRatio,
|  | MemPtr * | outputPP,
|  | UInt32 * | outputSizeP |
| ) |  |  |

Resizes a JPEG in memory.

This routine resizes a JPEG in memory to any size. The routine follows the same semantics as ImageLibResize, except that it creates a new JPEG in memory as a result.

See also:
  ImageLibResize

Parameters:

  | libRef,: | IN: Library reference number.
  | jpegInputP,: | IN: Pointer to a JPEG image in memory.
  | inputSize,: | IN: Size of the source image in bytes.
  | widthP,: | IN,OUT: On output, contains the new width of the image. On input, if maintainAspectRatio is true, determines the max width that the image should be. If maintainAspectRatio is false, determines the exact width that the image should be after resizing.
  | heightP,: | IN,OUT: On output, contains the new width of the image. On input, if maintainAspectRatio is true, determines the max width that the image should be. If maintainAspectRatio is false, determines the exact width that the image should be after resizing.
  | maintainAspectRatio,: | IN: If true, tells the library to maintain the aspect ratio of the image. In this case, the input values of widthP and heightP serve as maximum guidelines. If false, the image is stretched to fit the input values of widthP and heightP. the dimensions that an image would be if it was forced to draw in a box bounded by widthP and heightP.
  | outputPP,: | OUT: Pointer to the newly sized JPEG. The caller is responsible for freeing this memory.
  | outputSizeP,: | OUT: Size in bytes of the newly sized JPEG.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibResizeVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | Coord * | widthP,
|  | Coord * | heightP,
|  | Boolean | maintainAspectRatio |
| ) |  |  |

Resizes an image on a VFS volume to any arbitrary size.

This routine resizes a VFS image to any size. The routine follows the same semantics as ImageLibResize.

See also:
  ImageLibResize

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture.jpg")
  | widthP,: | IN,OUT: On output, contains the new width of the image. On input, if maintainAspectRatio is true, determines the max width that the image should be. If maintainAspectRatio is false, determines the exact width that the image should be after resizing.
  | heightP,: | IN,OUT: On output, contains the new width of the image. On input, if maintainAspectRatio is true, determines the max width that the image should be. If maintainAspectRatio is false, determines the exact width that the image should be after resizing.
  | maintainAspectRatio,: | IN: If true, tells the library to maintain the aspect ratio of the image. In this case, the input values of widthP and heightP serve as maximum guidelines. If false, the image is stretched to fit the input values of widthP and heightP. the dimensions that an image would be if it was forced to draw in a box bounded by widthP and heightP.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibSetImageID | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | const char * | mediaIDP,
|  | const char * | containerIDP |
| ) |  |  |

Sets the media and container IDs for an image in the database.

The media ID and container ID should both be 21 bytes in size. The image library copies 21 bytes from the supplied buffers into the main record for the image.

See also:
  ImageLibGetImageID

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of image.
  | mediaIDP,: | IN: Media ID.
  | containerIDP,: | IN: Container ID.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibSetImageInfo | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | const char * | name,
|  | UInt16 * | categoryP |
| ) |  |  |

Assigns information about an image stored in the database.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: Index of the picture
  | name,: | IN: Name of the picture. Pass NULL for this parameter if you don't want to set it.
  | categoryP,: | OUT: Category that that picture is assigned to. Pass NULL for this parameter if you don't want to set it.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibSetJPEGQuality | ( | UInt16 | libRef,
|  | Int32 | value |
| ) |  |  |

Sets the compression factor for all JPEG compression operations performed by the imaging library. The compression factor shoule be a value in the range of 1-99.

Parameters:

  | libRef,: | IN: Library reference number.
  | value,: | IN: new compression quality.

Return values:

  | Err | 0 on success, non-zero on error.

void ImageLibSetProgressCallback | ( | UInt16 | libRef,
|  | ImageLibProgressCallbackType | callback |
| ) |  |  |

Sets a progress callback function. The image library will invoke this routine periodically during long processing, such as compressing or decompressing a jpeg or resizing an image.

All of the APIs that decompress or resize images use the callback mechanism. ImageLibImageSave also invokes it.

max is the total number of operations that must be performed. For a JPEG compression or decompression, this equates to the number of horizontal scan lines in the image. The progress value will range from 0 to max. The imaging library will invoked the callback repeatedly. On each pass, the progress variable will increase by some unspecified amount. The operation argument determines the type of operation being performed. Possible values are kResizeOperation, kJPEGOperation, and kVFSOperation.

The callback function should have the following signature:

     void callback(Int32 progress, Int32 max, Int8 operation);

Parameters:

  | libRef,: | IN: Library reference number.
  | callback,: | IN: Address of the callback function. Pass NULL to reset the callback to nothing.

Return values:

  | void |

BitmapType* ImageLibThumbnailBitmapCreate | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | Err * | errP |
| ) |  |  |

Creates a 16 bit bitmap for holding an thumbnail image . If recIndex is a valid image index, the thumbnail for that image is loaded into the resulting bitmap. Otherwise, the result is an empty bitmap.

When called from a 68k application, the return value should be treated as opaque. The bitmap can safely be passed to the Palm OS bitmap routines, but 68k applications should not attempt to dereference members of the bitmap structure directly.

Bitmaps created with this function should be disposed of by calling ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.

If an error occurs, this function returns NULL and writes an error code to errP. If the function returns a non-NULL bitmap value, then *errP will always be 0.

The thumbnail is generated on the fly if the image in the database does not have a thumbnail record.

See also:
  ImageLibBitmapDelete

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: index of image to fill the thumbnail bitmap with. Use kInvalidRecIndex to create an empty 40x30, 16 bit bitmap.
  | errP,: | OUT: If the function succeeds, 0 is written to errP. Otherwise, a non-zero error code is written. This parameter should not be NULL.

Return values:

  | BitmapType* | On success, the result is a new bitmap with a bit depth of 16. On error, the result is NULL.

BitmapType* ImageLibThumbnailBitmapCreateFromVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | Err * | errP |
| ) |  |  |

Creates a 16 bit bitmap for holding an thumbnail image for a VFS JPEG.

When called from a 68k application, the return value should be treated as opaque. The bitmap can safely be passed to the Palm OS bitmap routines, but 68k applications should not attempt to dereference members of the bitmap structure directly.

Bitmaps created with this function should be disposed of by calling ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.

If an error occurs, this function returns NULL and writes an error code to errP. If the function returns a non-NULL bitmap value, then *errP will always be 0.

The thumbnail is generated on the fly from VFS file. For large images, this operation can be slow.

See also:
  ImageLibBitmapDelete

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture001.jpg")
  | errP,: | OUT: If the function succeeds, 0 is written to errP. Otherwise, a non-zero error code is written. This parameter should not be NULL.

Return values:

  | BitmapType* | On success, the result is a new bitmap with a bit depth of 16. On error, the result is NULL.

Err ImageLibThumbnailBitmapFill | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | BitmapType * | imageP |
| ) |  |  |

Fills a bitmap with an thumbnail image from the database.

The imageP argument should represent a bitmap created with ImageLibThumbnailBitmapCreate.

The image from the database is resampled as necessary to fit the dimensions of imageP. If the aspect ratio of imageP does not match the aspect ratio of the picture, the picture is stretched to fit.

See also:
  ImageLibThumbnailBitmapCreate

  ImageLibBitmapDelete

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: index of image
  | imageP,: | IN,OUT: Bitmap to fill.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibThumbnailBitmapFillFromVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | BitmapType * | imageP |
| ) |  |  |

Fills a bitmap with a thumbnail image from a VFS volume. *

The imageP argument should represent a bitmap created with ImageLibThumbnailBitmapCreate or ImageLibThumbnailBitmapCreateFromVFS.

The image is resampled as necessary to fit the dimensions of imageP.

See also:
  ImageLibThumbnailBitmapCreate

  ImageLibThumbnailBitmapCreateFromVFS

  ImageLibBitmapDelete

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture001.jpg")
  | imageP,: | IN,OUT: Bitmap to fill.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibThumbnailDraw | ( | UInt16 | libRef,
|  | UInt16 | recIndex,
|  | Coord | x,
|  | Coord | y |
| ) |  |  |

Draws an thumbnail image from the database to the current draw window at x,y. x and y * are window relative coordinates.

Parameters:

  | libRef,: | IN: Library reference number.
  | recIndex,: | IN: index of image
  | x,: | IN: x location to draw the preview image, relative to the current draw window.
  | y,: | IN: y location to draw the preview image, relative to the current draw window.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibThumbnailDrawFromVFS | ( | UInt16 | libRef,
|  | UInt16 | volRefNum,
|  | const char * | fileName,
|  | Coord | x,
|  | Coord | y |
| ) |  |  |

Draws an thumbnail image from a VFS image to the current draw window at x,y. x and y * are window relative coordinates.

Parameters:

  | libRef,: | IN: Library reference number.
  | volRefNum,: | IN: Ref number of the VFS volume
  | fileName,: | IN: Filename of the image (ie "/DCIM/picture001.jpg")
  | x,: | IN: x location to draw the preview image, relative to the current draw window.
  | y,: | IN: y location to draw the preview image, relative to the current draw window.

Return values:

  | Err | 0 on success, non-zero on error.

Err ImageLibTurnCameraOff | ( | UInt16 | libRef | ) |

Deactivates the camera hardware by unloading the camera driver.

Parameters:

  | libRef,: | IN: Library reference number.

Return values:

  | Err | 0 on success, non-zero on error.

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:07:35 2008 for Palm API Guide