API Guide Home (Online version only) |

# ImageLib.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @ingroup Imaging
    00007  */
    00008
    00009 /**
    00010  * @file  ImageLib.h
    00011  * @brief Public 68k include file for the Imaging Library.
    00012  *
    00013  * This file contains routines for capturing, storing, iterating, resizing, and
    00014  * manipulating images. The imaging library is a client of both the camera
    00015  * driver and the JPEG library.
    00016  */
    00017
    00018 /*
    00019  * Copyright (c) 2003 IDEO. All rights reserved.
    00020  * Portions ©2004 palmOne, Inc. All rights reserved.
    00021  *
    00022  *
    00023  ****************************************************************/
    00024
    00025 #ifndef IMAGELIB_H
    00026 #define IMAGELIB_H
    00027
    00028 #include <PalmOS.h>
    00029 #include <PalmTypes.h>
    00030 #include <VFSMgr.h>
    00031
    00032 #ifdef __cplusplus
    00033 extern "C" {
    00034 #endif
    00035
    00036 /****************************************************************/
    00037 /* ImageLibOpen */
    00038
    00039 /**
    00040  * Library open call for 68k clients of the library. This routine maps to the
    00041  * sysLibTrapOpen trap.
    00042  *
    00043  * It is customary for shared libraries to provide open and close functions.
    00044  * The open and close functions in ImageLib are empty stubs that exist for the
    00045  * sole purpose of adhering to past convention. This function does nothing and
    00046  * will always return errNone. All library initialization is done from
    00047  * PilotMain.
    00048  *
    00049  * This function is not available to ARM clients of the library.
    00050  *
    00051  * @param libRef: IN: Library reference number.
    00052  *
    00053  * @retval Err 0 on success or error code on failure.
    00054  *
    00055  ****************************************************************/
    00056 Err ImageLibOpen(UInt16 libRef) SYS_TRAP(kImageLibTrapOpen );
    00057
    00058
    00059 /****************************************************************/
    00060 /* ImageLibClose */
    00061
    00062 /**
    00063  * Library close function for 68k clients of the library. This routine maps to
    00064  * the sysLibTrapClose trap.
    00065  *
    00066  * This function is an empty stub (see comments for ImageLibOpen). All library
    00067  * cleanup is done from PilotMain.
    00068  *
    00069  * This function is not available to ARM clients of the library.
    00070  *
    00071  * @see ImageLibOpen
    00072  *
    00073  * @param libRef:   IN: Library reference number.
    00074  *
    00075  * @retval Err 0 on success or error code on failure.
    00076  *
    00077  ****************************************************************/
    00078 Err ImageLibClose(UInt16 libRef) SYS_TRAP(kImageLibTrapClose);
    00079
    00080
    00081 /****************************************************************/
    00082 /* ImageLibGetVersion */
    00083
    00084 /**
    00085  * Retrieves the version number of the image library.
    00086  *
    00087  * @param libRef: IN: Library reference number.
    00088  * @param dwVerP: OUT: Pointer to library version variable.
    00089  *
    00090  * @retval Err 0 on success or error code on failure.
    00091  *
    00092  ****************************************************************/
    00093 Err ImageLibGetVersion(UInt16 libRef, UInt32 *dwVerP)
    00094     SYS_TRAP(kImageLibTrapGetVersion);
    00095
    00096
    00097 /****************************************************************/
    00098 /* ImageLibCameraExists */
    00099
    00100 /**
    00101  * Detects presence of camera driver.
    00102  *
    00103  * The imaging library loads the camera driver dynamically. If the driver was
    00104  * found and was loaded successfully, ImageLibCameraExists writes true to
    00105  * existsP, otherwise it writes false.
    00106  *
    00107  * This routine will attempt to load the camera driver if it hasn't
    00108  * already been loaded. The driver will remain loaded until the imaging library
    00109  * is unloaded, or until ImageLibTurnCameraOff is called.
    00110  *
    00111  * @see ImageLibTurnCameraOff
    00112  *
    00113  * @param libRef:   IN: Library reference number.
    00114  * @param existsP:  OUT: true if camera successfully loaded. Otherwise false.
    00115  * @retval Err 0 on success or error code on failure.
    00116  *
    00117  ****************************************************************/
    00118 Err ImageLibCameraExists(UInt16 libRef, Boolean* existsP)
    00119     SYS_TRAP(kImageLibTrapCameraExists);
    00120
    00121 /****************************************************************/
    00122 /* ImageLibImageCapture */
    00123
    00124 /**
    00125  * Captures an image and stores it in the database.
    00126  *
    00127  * Images are appended to the end of the database.
    00128  *
    00129  * The camera driver always captures 640x480 images. If fullSize is false,
    00130  * the data from the camera is downsampled to 160x120 using a filtering
    00131  * algorithm.
    00132  *
    00133  * Captures are currently done in 16 bit RGB mode. Capturing an image
    00134  * requires at least 600 kB of free space in the dynamic heap (640x480x2).
    00135  *
    00136  * Captured pictures are stored in uncompressed palmOS bitmap format.
    00137  * To compress an image as a JPEG, call ImageLibImageSave.
    00138  *
    00139  * @see ImageLibImageSave
    00140  *
    00141  * @param libRef:           IN: Library reference number.
    00142  * @param fullsize:         IN: true capture a 640x480 image. false to capture 160x120
    00143  * @param playShutterSound: IN: true to play a camera shutter sound.
    00144  * @param drawImmediately:  IN: true to immediately draw the captured image to the current draw window.
    00145  * @param x:                IN: x location to draw the captured image. Relative to the current draw window. Ignored if drawImmediately is false.
    00146  * @param y:                IN: y location to draw the captured image. Relative to the current draw window. Ignored if drawImmediately is false.
    00147  * @param 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.
    00148  * @retval Err 0 on success or error code on failure.
    00149  *
    00150  ****************************************************************/
    00151 Err ImageLibImageCapture(UInt16 libRef,
    00152                          Boolean fullsize,
    00153                          Boolean playShutterSound,
    00154                          Boolean drawImmediately,
    00155                          Coord x,
    00156                          Coord y,
    00157                          UInt16 *newRecNoP)
    00158     SYS_TRAP(kImageLibTrapImageCapture);
    00159
    00160
    00161 /****************************************************************/
    00162 /* ImageLibImageSave */
    00163
    00164 /**
    00165  * Compresses a captured image to JPEG format.
    00166  *
    00167  * Compresses a captured image to JPEG, sets the image name, and sets the
    00168  * category of the picture. After saving, the uncompressed bitmap data is
    00169  * discarded and replaced with the JPEG version of the image.
    00170  *
    00171  * This routine should only be invoke on newly captured images, and it
    00172  * should only be called once per picture.
    00173  *
    00174  * @see ImageLibImageCapture
    00175  *
    00176  * @param libRef:   IN: Library reference number.
    00177  * @param recIndex: IN: Index of the image to compress.
    00178  * @param name:     IN: Name of the picture
    00179  * @param category: IN: Category to store the image in
    00180  * @retval Err 0 on success or error code on failure.
    00181  *
    00182  ****************************************************************/
    00183 Err ImageLibImageSave(UInt16 libRef,UInt16 recIndex,
    00184                       const char * name, UInt16 category)
    00185     SYS_TRAP(kImageLibTrapImageSave);
    00186
    00187
    00188 /****************************************************************/
    00189 /* ImageLibPreviewBitmapCreate */
    00190
    00191 /**
    00192  * Creates a preview bitmap. If Compresses a captured image to JPEG, sets the image name, and sets the
    00193  * category of the picture. After saving, the uncompressed bitmap data is
    00194  * discarded and replaced with the JPEG version of the image.
    00195  *
    00196  * When called from a 68k application, the return value should be treated
    00197  * as opaque. The bitmap can safely be passed to the Palm OS bitmap routines,
    00198  * but 68k applications should not attempt to dereference members of the bitmap
    00199  * structure directly.
    00200  *
    00201  * Bitmaps created with this function should be disposed of by calling
    00202  * ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.
    00203  *
    00204  * If an error occurs, this function returns NULL and writes an error code
    00205  * to errP. If the function returns a non-NULL bitmap value, then *errP will
    00206  * always be 0.
    00207  *
    00208  * This function does not perform an image preview. The resulting bitmap
    00209  * is empty. To fill the bitmap with a preview image, pass it to
    00210  * ImageLibPreviewBitmapFill.
    00211  *
    00212  * @see ImageLibPreviewBitmapFill
    00213  * @see ImageLibBitmapDelete
    00214  *
    00215  * @param   libRef: IN: Library reference number.
    00216  * @param   errP:   OUT: 0 on success, non-zero on error. This parameter should not be null.
    00217  * @retval  BitmapType On success, the result is a new 160x120 bitmap whose bit depth matches
    00218  *                     the bit depth of the screen. On failure, the result is NULL
    00219  *
    00220  ****************************************************************/
    00221 BitmapType* ImageLibPreviewBitmapCreate(UInt16 libRef, Err *errP)
    00222     SYS_TRAP(kImageLibTrapPreviewBitmapCreate);
    00223
    00224 /****************************************************************/
    00225 /* ImageLibPreviewBitmapFill */
    00226
    00227 /**
    00228  * Fills a bitmap with a preview image from the camera.
    00229  *
    00230  * The imageP argument should represent a bitmap created with
    00231  * ImageLibPreviewBitmapCreate.
    00232  *
    00233  * @see ImageLibPreviewBitmapCreate
    00234  * @see ImageLibBitmapDelete
    00235  * @see ImageLibPreviewStop
    00236  * @see ImageLibPreviewStart
    00237  *
    00238  * @param   libRef: IN: Library reference number.
    00239  * @param   imageP: IN,OUT: Bitmap to fill with a preview.
    00240  * @retval  Err 0 on success, non-zero on error.
    00241  *
    00242  ****************************************************************/
    00243 Err ImageLibPreviewBitmapFill(UInt16 libRef, BitmapType* imageP)
    00244     SYS_TRAP(kImageLibTrapPreviewBitmapFill);
    00245
    00246
    00247 /****************************************************************/
    00248 /* ImageLibPreviewDraw */
    00249
    00250 /**
    00251  * Draws a preview image to the current draw window.
    00252  *
    00253  * Snaps a preview image with the camera driver and then draws it to the
    00254  * current draw window at x,y. x and y are relative coordinates.
    00255  *
    00256  * @see ImageLibPreviewStop
    00257  * @see ImageLibPreviewStart
    00258  *
    00259  * @param   libRef: IN: Library reference number.
    00260  * @param   x:      IN: x location to draw the preview image, relative to the current draw window.
    00261  * @param   y:      IN: y location to draw the preview image, relative to the current draw window.
    00262  * @retval  Err 0 on success, non-zero on error.
    00263  *
    00264  ****************************************************************/
    00265 Err ImageLibPreviewDraw(UInt16 libRef, Coord x, Coord y)
    00266     SYS_TRAP(kImageLibTrapPreviewDraw);
    00267
    00268
    00269
    00270 /****************************************************************/
    00271 /* ImageLibImageBitmapCreate */
    00272
    00273 /**
    00274  * Creates a 16 bit bitmap for holding an image from the database. If
    00275  * recIndex is a valid image index, that image is loaded into the resulting
    00276  * bitmap. Otherwise, the result is an empty picture.
    00277  *
    00278  * When called from a 68k application, the return value should be treated
    00279  * as opaque. The bitmap can safely be passed to the Palm OS bitmap routines,
    00280  * but 68k applications should not attempt to dereference members of the bitmap
    00281  * structure directly.
    00282  *
    00283  * Bitmaps created with this function should be disposed of by calling
    00284  * ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.
    00285  *
    00286  * If an error occurs, this function returns NULL and writes an error code
    00287  * to errP. If the function returns a non-NULL bitmap value, then *errP will
    00288  * always be 0.
    00289  *
    00290  * If recIndex is kInvalidRecIndex, the result is an empty 160x120 bitmap.
    00291  * If recIndex is not kInvalidRecIndex, the result is a bitmap that contains the
    00292  * given image from the database. The returned bitmap will be 160x120 if the
    00293  * image in the database is 160x120, 320x240, 640x480, or any other image larger
    00294  * than 160x120 with a 4:3 aspect ratio. If the image has a non-standard size,
    00295  * it is downsized to fit in a 160x120 box. The aspect ratio of the picture is
    00296  * preserved. Images that are less than 160x120 are not scaled at all.
    00297  *
    00298  * @see ImageLibBitmapDelete
    00299  * @see ImageLibPreviewStop
    00300  * @see ImageLibPreviewStart
    00301  *
    00302  * @param   libRef:     IN: Library reference number.
    00303  * @param   recIndex:   IN: Index of image to fill bitmap with. Use kInvalidRecIndex to create an empty 160x120, 16 bit bitmap.
    00304  * @param   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.
    00305  * @retval  BitmapType* On success, the result is a new bitmap with a bit depth of 16. On error, the result is NULL.
    00306  *
    00307  ****************************************************************/
    00308 BitmapType* ImageLibImageBitmapCreate(UInt16 libRef,
    00309                                       UInt16 recIndex,
    00310                                       Err *errP)
    00311     SYS_TRAP(kImageLibTrapImageBitmapCreate);
    00312
    00313
    00314 /****************************************************************/
    00315 /* ImageLibImageBitmapFill */
    00316
    00317 /**
    00318  * Fills a bitmap with an image from the database.
    00319  *
    00320  * The imageP argument should represent a bitmap created with
    00321  * ImageLibImageBitmapCreate.
    00322  *
    00323  * The image from the database is resampled as necessary to fit the
    00324  * dimensions of imageP. When the image is a jpeg, the DCT scaling features of
    00325  * the IJG library are used to get the image size close to the destination size.
    00326  * From there, the image is resampled with a filter to match the dimensions of
    00327  * imageP. If the aspect ratio of imageP does not match the aspect ratio of
    00328  * the picture, the picture is stretched to fit.
    00329  *
    00330  * @see ImageLibImageBitmapCreate
    00331  * @see ImageLibBitmapDelete
    00332  *
    00333  * @param   libRef:     IN:  Library reference number.
    00334  * @param   recIndex:   IN:  index of image to fill bitmap with.
    00335  * @param   imageP:     IN,OUT:  Bitmap to fill.
    00336  * @retval  Err 0 on success, non-zero on error.
    00337  *
    00338  ****************************************************************/
    00339 Err ImageLibImageBitmapFill(UInt16 libRef, UInt16 recIndex, BitmapType* imageP)
    00340     SYS_TRAP(kImageLibTrapImageBitmapFill);
    00341
    00342 /****************************************************************/
    00343 /* ImageLibImageDraw*/
    00344
    00345 /**
    00346  * Draws an image from the database to the current draw window.
    00347  *
    00348  * Draws an image from the database to the current draw window at x,y. x and y
    00349  * are window relative coordinates.
    00350  *
    00351  * If necessary, the image is downsized to fit in a 160x120 box. The
    00352  * aspect ratio of the picture is preserved.
    00353  *
    00354  * @param   libRef:     IN: Library reference number.
    00355  * @param   recIndex:   IN: index of image to draw.
    00356  * @param   x:          IN: x location to draw the preview image, relative to the current draw window.
    00357  * @param   y:          IN: y location to draw the preview image, relative to the current draw window.
    00358  * @retval  Err 0 on success, non-zero on error.
    00359  *
    00360  ****************************************************************/
    00361 Err ImageLibImageDraw(UInt16 libRef, UInt16 recIndex, Coord x, Coord y)
    00362     SYS_TRAP(kImageLibTrapImageDraw);
    00363
    00364
    00365 /****************************************************************/
    00366 /* ImageLibThumbnailBitmapCreate */
    00367
    00368 /**
    00369  * Creates a 16 bit bitmap for holding an thumbnail image . If
    00370  * recIndex is a valid image index, the thumbnail for that image is loaded into
    00371  * the resulting bitmap. Otherwise, the result is an empty bitmap.
    00372  *
    00373  * When called from a 68k application, the return value should be treated
    00374  * as opaque. The bitmap can safely be passed to the Palm OS bitmap routines,
    00375  * but 68k applications should not attempt to dereference members of the bitmap
    00376  * structure directly.
    00377  *
    00378  * Bitmaps created with this function should be disposed of by calling
    00379  * ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.
    00380  *
    00381  * If an error occurs, this function returns NULL and writes an error code
    00382  * to errP. If the function returns a non-NULL bitmap value, then *errP will
    00383  * always be 0.
    00384  *
    00385  * The thumbnail is generated on the fly if the image in the database
    00386  * does not have a thumbnail record.
    00387  *
    00388  * @see ImageLibBitmapDelete
    00389  *
    00390  * @param   libRef:     IN:  Library reference number.
    00391  * @param   recIndex:   IN:  index of image to fill the thumbnail bitmap with. Use kInvalidRecIndex to create an empty 40x30, 16 bit bitmap.
    00392  * @param   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.
    00393  * @retval  BitmapType* On success, the result is a new bitmap with a bit depth of 16. On error, the result is NULL.
    00394  *
    00395  ****************************************************************/
    00396 BitmapType* ImageLibThumbnailBitmapCreate(UInt16 libRef,
    00397                                           UInt16 recIndex,
    00398                                           Err *errP)
    00399     SYS_TRAP(kImageLibTrapThumbnailBitmapCreate);
    00400
    00401
    00402 /****************************************************************/
    00403 /* ImageLibThumbnailBitmapFill*/
    00404
    00405 /**
    00406  * Fills a bitmap with an thumbnail image from the database.
    00407  *
    00408  * The imageP argument should represent a bitmap created with
    00409  * ImageLibThumbnailBitmapCreate.
    00410  *
    00411  * The image from the database is resampled as necessary to fit the
    00412  * dimensions of imageP. If the aspect ratio of imageP does not match the aspect
    00413  * ratio of the picture, the picture is stretched to fit.
    00414  *
    00415  * @see ImageLibThumbnailBitmapCreate
    00416  * @see ImageLibBitmapDelete
    00417  *
    00418  * @param   libRef:     IN:  Library reference number.
    00419  * @param   recIndex:   IN: index of image
    00420  * @param   imageP:     IN,OUT:  Bitmap to fill.
    00421  * @retval  Err 0 on success, non-zero on error.
    00422  *
    00423  ****************************************************************/
    00424 Err ImageLibThumbnailBitmapFill(UInt16 libRef, UInt16 recIndex, BitmapType* imageP)  SYS_TRAP(kImageLibTrapThumbnailBitmapFill);
    00425
    00426
    00427 /****************************************************************/
    00428 /* ImageLibThumbnailDraw*/
    00429
    00430 /**
    00431  * Draws an thumbnail image from the database to the current draw window at x,y.
    00432  * x and y * are window relative coordinates.
    00433  *
    00434  * @param   libRef:     IN:  Library reference number.
    00435  * @param   recIndex:   IN:  index of image
    00436  * @param   x:          IN:  x location to draw the preview image, relative to the current draw window.
    00437  * @param   y:          IN:  y location to draw the preview image, relative to the current draw window.
    00438  * @retval  Err 0 on success, non-zero on error.
    00439  *
    00440  ****************************************************************/
    00441 Err ImageLibThumbnailDraw(UInt16 libRef, UInt16 recIndex, Coord x, Coord y)
    00442     SYS_TRAP(kImageLibTrapThumbnailDraw);
    00443
    00444
    00445 /****************************************************************/
    00446 /* ImageLibBitmapDelete*/
    00447
    00448 /**
    00449  * Deletes a bitmap created by the library.
    00450  *
    00451  * Use ImageLibBitmapDelete to delete any bitmap that was created and returned
    00452  * by the imaging library (ImageLibPreviewBitmapCreate, ImageLibImageBitmapCreate and ImageLibThumbnailBitmapCreate).
    00453  *
    00454  * @param   libRef: IN: Library reference number.
    00455  * @param   bmp:    IN: Bitmap to delete.
    00456  * @retval  Err 0 on success, non-zero on error.
    00457  *
    00458  ****************************************************************/
    00459 Err ImageLibBitmapDelete(UInt16 libRef, BitmapType *bmp)
    00460     SYS_TRAP(kImageLibTrapBitmapDelete);
    00461
    00462 /****************************************************************/
    00463 /* ImageLibDeleteImage*/
    00464
    00465 /**
    00466  * Delete a picture from the database.
    00467  *
    00468  * This routine deletes an image and its thumbnail from the database.
    00469  *
    00470  * Deleting a picture invalidates the record indices of all subsequent
    00471  * images in the database. Records are deleted with DmRemoveRecord. They are
    00472  * not archived.
    00473  *
    00474  * @param   libRef:     IN: Library reference number.
    00475  * @param   recIndex:   IN: index of image to delete.
    00476  * @retval  Err 0 on success, non-zero on error.
    00477  *
    00478  ****************************************************************/
    00479 Err ImageLibDeleteImage(UInt16 libRef, UInt16 recIndex)
    00480     SYS_TRAP(kImageLibTrapDeleteImage);
    00481
    00482 /****************************************************************/
    00483 /* ImageLibResizeImage*/
    00484
    00485 /**
    00486  * @deprecated
    00487  *
    00488  * Resizes a fullsize picture in the database to 160x120 (palm size). The original
    00489  * fullsize image is replaced with the palm size version.
    00490  *
    00491  * If the original image is a full size 640x480 jpeg, the image is
    00492  * downsampled using the DCT scaling features of the IJG library. This means
    00493  * that the JPEG is decompressed directly to 160x120, and then compressed again
    00494  * and saved back to the database.
    00495  *
    00496  * If the original image is not a 640x480 jpeg, it is scaled as much as
    00497  * possible using the IJG scaling features. After decompression, the picture is
    00498  * resampled with a filter to get its dimensions to 160x120.
    00499  *
    00500  * ImageLibResizeImage is deprecated. Use ImageLibResize instead.
    00501  *
    00502  * @param   libRef:     IN: Library reference number.
    00503  * @param   recIndex:   IN: index of image to resize.
    00504  * @retval  Err 0 on success, non-zero on error.
    00505  *
    00506  ****************************************************************/
    00507 Err ImageLibResizeImage(UInt16 libRef, UInt16 recIndex)
    00508     SYS_TRAP(kImageLibTrapResizeImage);
    00509
    00510
    00511 /****************************************************************/
    00512 /* ImageLibGetImageDatabases*/
    00513
    00514 /**
    00515  * Return the references to the database that are used to store pictures.
    00516  *
    00517  * The image library opens each database when it is loaded, and closes them when it is unloaded.
    00518  * Do not close the database references that are returned by this function because the references are still being used by
    00519  * the imaging library.
    00520  *
    00521  * The data in each database is stored in little endian format.
    00522  *
    00523  * The main database contains one record for each image in the database.
    00524  * Each record has a fixed size and contains information about the picture. The
    00525  * image database contains the actual JPEG data for each image. The main
    00526  * database acts as a master table and the images database is a child table.
    00527  *
    00528  * The notes database is not currently used.
    00529  *
    00530  * The category of an image is determined by the category of its record in
    00531  * the main database. Categories are not used in the image table.
    00532  *
    00533  * @param   libRef:     IN:  Library reference number.
    00534  * @param   dbMainP:    OUT: Reference to the main database. Pass NULL for this parameter if you don’t want to retrieve it.
    00535  * @param   dbNoteP:    OUT: Reference to the note database. Pass NULL for this parameter if you don’t want to retrieve it.
    00536  * @param   dbImageP:   OUT: Reference to the images database.
    00537  * @retval  Err 0 on success, non-zero on error.
    00538  *
    00539  ****************************************************************/
    00540 Err ImageLibGetImageDatabases(UInt16 libRef, DmOpenRef *dbMainP,
    00541                               DmOpenRef *dbNoteP, DmOpenRef *dbImageP)
    00542     SYS_TRAP(kImageLibTrapGetImageDatabases);
    00543
    00544
    00545 /****************************************************************/
    00546 /* ImageLibGetImageInfo*/
    00547
    00548 /**
    00549  * Retrieves information about an image stored in the database.
    00550  *
    00551  * @param   libRef:         IN:  Library reference number.
    00552  * @param   recIndex:       IN:  Index of the picture
    00553  * @param   name:           OUT: Buffer to receive the name of the image. The buffer should be at least 32
    00554                                  characters long (31 + null terminator). Pass NULL for this parameter if you don't want to retrieve it.
    00555  * @param   fullSizeP:      OUT: true if image is 640x480, false if palm size. Pass NULL for this parameter if you don't want to retrieve it.
    00556  * @param   createdP:       OUT: Timestamp when picture was creatd. Pass NULL for this parameter if you don't want to retrieve it.
    00557  * @param   sizeP:          OUT: Size of the image data in bytes. Pass NULL for this parameter if you don't want to retrieve it.
    00558  * @param   categoryP:      OUT: Category that that picture is assigned to. Pass NULL for this parameter if you don't want to retrieve it.
    00559  * @param   categoryName:   OUT: Text description of the picture's category (ie 'Unfiled'). Pass NULL for this parameter if you don't want to retrieve it.
    00560  * @param   lockedP:        OUT: true if image is locked.
    00561  * @param   uidP:           OUT: Unique ID of the image.
    00562  * @retval  Err 0 on success, non-zero on error.
    00563  *
    00564  ****************************************************************/
    00565 Err ImageLibGetImageInfo(UInt16 libRef, UInt16 recIndex, Char* name,
    00566                          Boolean* fullSizeP, UInt32* createdP, UInt32* sizeP,
    00567                          UInt16* categoryP, Char* categoryName, Boolean *lockedP, UInt32 *uidP) SYS_TRAP(kImageLibTrapGetImageInfo);
    00568
    00569 /****************************************************************/
    00570 /* ImageLibSetImageInfo*/
    00571
    00572 /**
    00573  * Assigns information about an image stored in the database.
    00574  *
    00575  * @param   libRef:     IN:  Library reference number.
    00576  * @param   recIndex:   IN:  Index of the picture
    00577  * @param   name:       IN:  Name of the picture. Pass NULL for this parameter if you don't want to set it.
    00578  * @param   categoryP:  OUT: Category that that picture is assigned to. Pass NULL for this parameter if you don't want to set it.
    00579  * @retval  Err 0 on success, non-zero on error.
    00580  *
    00581  ****************************************************************/
    00582 Err ImageLibSetImageInfo(UInt16 libRef, UInt16 recIndex,
    00583                          const char* name, UInt16* categoryP)
    00584     SYS_TRAP(kImageLibTrapSetImageInfo);
    00585
    00586
    00587 /****************************************************************/
    00588 /* ImageLibCopyImageToVFS*/
    00589
    00590 /**
    00591  * Copies an image from the database to a VFS volume.
    00592  *
    00593  * Copies an image from the database to a VFS volume, overwriting any previous
    00594  * file that existed on the volume with the same name.
    00595  *
    00596  * volRefNum should be obtained via a call to VFSVolumeEnumerate
    00597  *
    00598  * @param   libRef:     IN:  Library reference number.
    00599  * @param   recIndex:   IN:  Index of the picture
    00600  * @param   volRefNum:  IN:  Ref number of the VFS volume
    00601  * @param   fileName:   IN:  Filename of the image (ie "/DCIM/picture.jpg")
    00602  * @retval  Err 0 on success, non-zero on error.
    00603  *
    00604  ****************************************************************/
    00605 Err ImageLibCopyImageToVFS(UInt16 libRef, UInt16 recIndex,
    00606                            UInt16 volRefNum, const char* fileName)
    00607     SYS_TRAP(kImageLibTrapCopyImageToVFS);
    00608
    00609
    00610 /****************************************************************/
    00611 /* ImageLibCopyImageToVFS*/
    00612
    00613 /**
    00614  * Copies an image from a VFS volume to the database.
    00615  *
    00616  * volRefNum should be obtained via a call to VFSVolumeEnumerate
    00617  *
    00618  * If a picture with a matching name and category already exists in the
    00619  * database, that image is <b>not</b> overwritten. After the call, there will
    00620  * be two images with the same name and category.
    00621  *
    00622  * @param   libRef:         IN:  Library reference number.
    00623  * @param   volRefNum:      IN:  Ref number of the VFS volume
    00624  * @param   fileName:       IN:  Filename of the image (ie "/DCIM/picture001.jpg")
    00625  * @param   name:           IN:  Name of the image in the database (ie "picture001")
    00626  * @param   category:       IN:  Category that the image should be assigned to
    00627  * @param   newRecIndexP:   OUT: Record index of the newly stored picture. Pass NULL if you don't care what the new index is.
    00628  * @retval  Err 0 on success, non-zero on error.
    00629  *
    00630  ****************************************************************/
    00631 Err ImageLibCopyImageFromVFS(UInt16 libRef, UInt16 volRefNum,
    00632                              const char* fileName, const char * name,
    00633                              UInt16 category, UInt16 *newRecIndexP)
    00634     SYS_TRAP(kImageLibTrapCopyImageFromVFS);
    00635
    00636
    00637 /****************************************************************/
    00638 /* ImageLibImageBitmapCreateFromVFS */
    00639
    00640 /**
    00641  * Creates a 16 bit bitmap for holding an image from a VFS volume. The library
    00642  * decompresses the image from the volume and stores it in the result.
    00643  *
    00644  * When called from a 68k application, the return value should be treated
    00645  * as opaque. The bitmap can safely be passed to the Palm OS bitmap routines,
    00646  * but 68k applications should not attempt to dereference members of the bitmap
    00647  * structure directly.
    00648  *
    00649  * Bitmaps created with this function should be disposed of by calling
    00650  * ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.
    00651  *
    00652  * If an error occurs, this function returns NULL and writes an error code
    00653  * to errP. If the function returns a non-NULL bitmap value, then *errP will
    00654  * always be 0.
    00655  *
    00656  * The picture is always resized to fit in a 160x120 box. If the image needs
    00657  * to be resized, its aspect ratio is maintained.
    00658  *
    00659  * @see ImageLibBitmapDelete
    00660  *
    00661  * @param   libRef:     IN:  Library reference number.
    00662  * @param   volRefNum:  IN:  Ref number of the VFS volume
    00663  * @param   fileName:   IN:  Filename of the image (ie "/DCIM/picture.jpg")
    00664  * @param   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.
    00665  * @retval  BitmapType* On success, the result is a new bitmap with a bit depth of 16. On error, the result is NULL.
    00666  *
    00667  ****************************************************************/
    00668 BitmapType* ImageLibImageBitmapCreateFromVFS(UInt16 libRef, UInt16 volRefNum,
    00669                                              const char* fileName, Err *errP)
    00670     SYS_TRAP(kImageLibTrapImageBitmapCreateFromVFS);
    00671
    00672
    00673 /****************************************************************/
    00674 /* ImageLibImageBitmapFillFromVFS */
    00675
    00676 /**
    00677  *
    00678  * Fills a 16 bit bitmap with an image from a VFS volume. The library
    00679  * decompresses the image from the volume and stores it in the supplied bitmap.
    00680  * The image is resized to fit the dimensions of the supplied bitmap.
    00681  *
    00682  * The imageP argument should represent a bitmap created with
    00683  * ImageLibImageBitmapCreate or ImageLibImageBitmapCreateFromVFS.
    00684  *
    00685  * The image is resampled as necessary to fit the
    00686  * dimensions of imageP. When the image is a jpeg, the DCT scaling features of
    00687  * the IJG library are used to get the image size close to the destination size.
    00688  * From there, the image is resampled with a filter to match the dimensions of
    00689  * imageP. If the aspect ratio of imageP does not match the aspect ratio of
    00690  * the picture, the picture is stretched to fit.
    00691  *
    00692  * @see ImageLibImageBitmapCreate
    00693  * @see ImageLibImageBitmapCreateFromVFS
    00694  * @see ImageLibBitmapDelete
    00695  *
    00696  * @param   libRef:     IN:  Library reference number.
    00697  * @param   volRefNum:  IN:  Ref number of the VFS volume
    00698  * @param   fileName:   IN:  Filename of the image (ie "/DCIM/picture001.jpg")
    00699  * @param   imageP:     IN,OUT:  Bitmap to fill.
    00700  * @retval  Err 0 on success, non-zero on error.
    00701  *
    00702  ****************************************************************/
    00703 Err ImageLibImageBitmapFillFromVFS(UInt16 libRef, UInt16 volRefNum,
    00704                                    const char* fileName, BitmapType* imageP)
    00705     SYS_TRAP(kImageLibTrapImageBitmapFillFromVFS);
    00706
    00707
    00708 /****************************************************************/
    00709 /* ImageLibImageDrawFromVFS*/
    00710
    00711 /**
    00712  * Draws an image from from a VFS volume to the current draw window at x,y.
    00713  * x and y are window relative coordinates.
    00714  *
    00715  * If necessary, the image is downsized to fit in a 160x120 box. The
    00716  * aspect ratio of the picture is preserved.
    00717  *
    00718  * @param   libRef:     IN:  Library reference number.
    00719  * @param   volRefNum:  IN:  Ref number of the VFS volume
    00720  * @param   fileName:   IN:  Filename of the image (ie "/DCIM/picture001.jpg")
    00721  * @param   x:          IN:  x location to draw the image, relative to the current draw window.
    00722  * @param   y:          IN:  y location to draw the image, relative to the current draw window.
    00723  * @retval  Err 0 on success, non-zero on error.
    00724  *
    00725  ****************************************************************/
    00726 Err ImageLibImageDrawFromVFS(UInt16 libRef, UInt16 volRefNum,
    00727                              const char* fileName, Coord x, Coord y)
    00728     SYS_TRAP(kImageLibTrapImageDrawFromVFS);
    00729
    00730
    00731 /****************************************************************/
    00732 /* ImageLibThumbnailBitmapCreateFromVFS */
    00733
    00734 /**
    00735  * Creates a 16 bit bitmap for holding an thumbnail image for a VFS JPEG.
    00736  *
    00737  * When called from a 68k application, the return value should be treated
    00738  * as opaque. The bitmap can safely be passed to the Palm OS bitmap routines,
    00739  * but 68k applications should not attempt to dereference members of the bitmap
    00740  * structure directly.
    00741  *
    00742  * Bitmaps created with this function should be disposed of by calling
    00743  * ImageLibBitmapDelete. Do note call BmpDelete or MemPtrFree.
    00744  *
    00745  * If an error occurs, this function returns NULL and writes an error code
    00746  * to errP. If the function returns a non-NULL bitmap value, then *errP will
    00747  * always be 0.
    00748  *
    00749  * The thumbnail is generated on the fly from VFS file. For large images,
    00750  * this operation can be slow.
    00751  *
    00752  * @see ImageLibBitmapDelete
    00753  *
    00754  * @param   libRef:     IN:  Library reference number.
    00755  * @param   volRefNum:  IN:  Ref number of the VFS volume
    00756  * @param   fileName:   IN:  Filename of the image (ie "/DCIM/picture001.jpg")
    00757  * @param   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.
    00758  * @retval  BitmapType* On success, the result is a new bitmap with a bit depth of 16. On error, the result is NULL.
    00759  *
    00760  ****************************************************************/
    00761 BitmapType* ImageLibThumbnailBitmapCreateFromVFS (UInt16 libRef,
    00762                                                   UInt16 volRefNum,
    00763                                                   const char* fileName,
    00764                                                   Err *errP)
    00765     SYS_TRAP(kImageLibTrapThumbnailBitmapCreateFromVFS);
    00766
    00767
    00768 /****************************************************************/
    00769 /* ImageLibImageBitmapFillFromVFS */
    00770
    00771 /**
    00772  * Fills a bitmap with a thumbnail image from a VFS volume. *
    00773  *
    00774  * The imageP argument should represent a bitmap created with
    00775  * ImageLibThumbnailBitmapCreate or ImageLibThumbnailBitmapCreateFromVFS.
    00776  *
    00777  * The image is resampled as necessary to fit the
    00778  * dimensions of imageP.
    00779  *
    00780  * @see ImageLibThumbnailBitmapCreate
    00781  * @see ImageLibThumbnailBitmapCreateFromVFS
    00782  * @see ImageLibBitmapDelete
    00783  *
    00784  * @param   libRef:     IN:  Library reference number.
    00785  * @param   volRefNum:  IN:  Ref number of the VFS volume
    00786  * @param   fileName:   IN:  Filename of the image (ie "/DCIM/picture001.jpg")
    00787  * @param   imageP:     IN,OUT:  Bitmap to fill.
    00788  * @retval  Err 0 on success, non-zero on error.
    00789  *
    00790  ****************************************************************/
    00791 Err ImageLibThumbnailBitmapFillFromVFS(UInt16 libRef, UInt16 volRefNum,
    00792                                        const char* fileName, BitmapType* imageP)
    00793     SYS_TRAP(kImageLibTrapThumbnailBitmapFillFromVFS);
    00794
    00795 /****************************************************************/
    00796 /* ImageLibThumbnailDrawFromVFS*/
    00797
    00798 /**
    00799  * Draws an thumbnail image from a VFS image to the current draw window at x,y.
    00800  * x and y * are window relative coordinates.
    00801  *
    00802  * @param   libRef:     IN:  Library reference number.
    00803  * @param   volRefNum:  IN:  Ref number of the VFS volume
    00804  * @param   fileName:   IN:  Filename of the image (ie "/DCIM/picture001.jpg")
    00805  * @param   x:          IN:  x location to draw the preview image, relative to the current draw window.
    00806  * @param   y:          IN:  y location to draw the preview image, relative to the current draw window.
    00807  * @retval  Err 0 on success, non-zero on error.
    00808  *
    00809  ****************************************************************/
    00810 Err ImageLibThumbnailDrawFromVFS(UInt16 libRef, UInt16 volRefNum, const char* fileName, Coord x, Coord y)   SYS_TRAP(kImageLibTrapThumbnailDrawFromVFS);
    00811
    00812
    00813 /****************************************************************/
    00814 /* ImageLibDoAttachImageDialog*/
    00815
    00816 /**
    00817  * Displays the attach image dialog.
    00818  *
    00819  * Displays the attach image dialog. Allows to user to select a picture from a
    00820  * list. After choosing an image, the selection is written to the output
    00821  * parameters recIndexP, volRefNum, and filename.
    00822  *
    00823  * If the user cancels the dialog, the return value is still 0. The values
    00824  * in recIndexP and volRefNumP indicate that the dialog was cancelled.
    00825  *
    00826  * @param   libRef:             IN:  Library reference number.
    00827  * @param   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.
    00828  * @param   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.
    00829  * @param   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.
    00830  * @param   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.
    00831  * @param   showConfirmation:   IN:  If true, a confirmation dialog will be displayed that shows the image in full size. If false, the confirmation dialog is skipped.
    00832  * @param   internalImagesOnly: IN:  If true, images from VFS volumes are not displayed to the user.
    00833  * @param   dialogTitle:        IN:  The string to display as the title of the dialog. Pass null to display a localized default.
    00834  * @param   btnTitle:           IN:  The string to display as the title of the OK button. Pass null to display a localized default.
    00835  * @retval  Err 0 on success, non-zero on error.
    00836  *
    00837  ****************************************************************/
    00838 Err ImageLibDoAttachImageDialog(UInt16 libRef,
    00839                                 UInt16 *recIndexP,
    00840                                 UInt16 *volRefNumP,
    00841                                 char* fileName,
    00842                                 UInt16 initialCategory,
    00843                                 Boolean showConfirmation,
    00844                                 Boolean internalImagesOnly,
    00845                                 const char *dialogTitle,
    00846                                 const char * btnTitle)
    00847     SYS_TRAP(kImageLibTrapDoAttachImageDialog);
    00848
    00849
    00850 /****************************************************************/
    00851 /* ImageLibCopyImageToBuffer*/
    00852
    00853 /**
    00854  * Copies a JPEG from the image database to a chunk of memory at bufP. The
    00855  * allocated memory block must be large enough to hold the entire blob of JPEG
    00856  * data. The size of the JPEG can be determined with ImageLibGetImageInfo.
    00857  *
    00858  * Fullsize images may requires that bufP be larger than 64 kB. Use
    00859  * FtrPtrNew or MemChunkNew to create buffers larger than 64 kB. Otherwise,
    00860  * consider using ImageLibCopyImageToFile instead.
    00861  *
    00862  * @see ImageLibGetImageInfo
    00863  * @see ImageLibCopyImageToFile
    00864  *
    00865  * @param   libRef:     IN:  Library reference number.
    00866  * @param   recIndex:   IN:  Index of the picture
    00867  * @param   bufP:       IN,OUT: Pointer to the block of memory that should receive the image.
    00868  * @retval  Err 0 on success, non-zero on error.
    00869  *
    00870  ****************************************************************/
    00871 Err ImageLibCopyImageToBuffer (UInt16 libRef, UInt16 recIndex, MemPtr bufP)
    00872     SYS_TRAP(kImageLibTrapCopyImageToBuffer     );
    00873
    00874
    00875 /****************************************************************/
    00876 /* ImageLibCopyImageToFile*/
    00877
    00878 /**
    00879  * Copies a JPEG from the image database to a Palm OS file stream. The library
    00880  * writes to the file stream at its current postion. When done, the library
    00881  * leaves the file handle pointing to the end of the file. To see the jpeg data,
    00882  * the file handle should be rewound to its original location.
    00883  *
    00884  * @param   libRef:     IN:  Library reference number.
    00885  * @param   recIndex:   IN:  Index of the picture
    00886  * @param   fileH:      IN:  Handle to an open file stream.
    00887  * @retval  Err 0 on success, non-zero on error.
    00888  *
    00889  ****************************************************************/
    00890 Err ImageLibCopyImageToFile (UInt16 libRef, UInt16 recIndex, FileHand fileH)
    00891     SYS_TRAP(kImageLibTrapCopyImageToFile);
    00892
    00893
    00894 /****************************************************************/
    00895 /* ImageLibInsertImageFromBuffer*/
    00896
    00897 /**
    00898  * Inserts a JPEG blob into the image database, storing it with the supplied
    00899  * name and category.
    00900  *
    00901  * @param   libRef:         IN:  Library reference number.
    00902  * @param   bufP:           IN:  Pointer to a JPEG image in memory.
    00903  * @param   size:           IN:  Size of the source image in bytes.
    00904  * @param   name:           IN:  Name of the new image (ie "Picture001")
    00905  * @param   category:       IN:  The category to store the image in. Pass 0 for unfiled.
    00906  * @param   newRecIndexP:   OUT: Index of the newly created image. Pass NULL if you don’t care about this value.
    00907  * @retval  Err 0 on success, non-zero on error.
    00908  *
    00909  ****************************************************************/
    00910 Err ImageLibInsertImageFromBuffer(UInt16 libRef, MemPtr bufP, UInt32 size,
    00911                                   const char * name, UInt16 category,
    00912                                   UInt16 *newRecIndexP)
    00913     SYS_TRAP(kImageLibTrapInsertImageFromBuffer );
    00914
    00915
    00916 /****************************************************************/
    00917 /* ImageLibInsertImageFromBuffer*/
    00918
    00919 /**
    00920  * Insert an image into the database from a Palm OS file stream. The file stream
    00921  * is read from its current position to the end of the stream. When the routine
    00922  * is finished, it leaves the stream open and performs a FileSeek back to the
    00923  * original position.
    00924  *
    00925  * @param   libRef:         IN:  Library reference number.
    00926  * @param   fileH:          IN:  Handle to an open file stream that contains a JPEG starting at its current position.
    00927  * @param   name:           IN:  Name of the new image (ie "Picture001")
    00928  * @param   category:       IN:  The category to store the image in. Pass 0 for unfiled.
    00929  * @param   newRecIndexP:   OUT: Index of the newly created image. Pass NULL if you don’t care about this value.
    00930  * @retval  Err 0 on success, non-zero on error.
    00931  *
    00932  ****************************************************************/
    00933 Err ImageLibInsertImageFromFile(UInt16 libRef, FileHand fileH,
    00934                                const char * name, UInt16 category,
    00935                                UInt16 *newRecIndexP)
    00936     SYS_TRAP(kImageLibTrapInsertImageFromFile   );
    00937
    00938
    00939 /****************************************************************/
    00940 /* ImageLibIterateImages*/
    00941
    00942 /**
    00943  * Creates an iterator for working with a collection of images in the database.
    00944  * When finished, the iterator refers to a data structure that contains images
    00945  * The iterator can be used to step through images, draw images, sort images, and search for
    00946  * images by name.
    00947  *
    00948  * The returned iterator handle can be passed to other iterator routines
    00949  * that take an iterator handle. The handle should be freed by calling
    00950  * ImageLibIterFree.
    00951  *
    00952  * @see ImageLibIterFree
    00953  *
    00954  * @param   libRef:         IN:  Library reference number.
    00955  * @param   category:       IN:  The category to search. Pass 0 for unfiled. Pass dmAllCategories to iterate through all images in the databse.
    00956  * @param   sortType:       IN:  Initial sort order of the datastructure (kNoSortOrder, kSortByName, or kSortByDate)
    00957  * @param   imageCountP:    OUT: Number of images in the iterator data structure. Pass NULL if you don't care about this value.
    00958  * @param   errP:           OUT: 0 on success, non-zero on error. This parameter should not be null.
    00959  * @retval  ImageIteratorHandle Opaque iterator handle.
    00960  *
    00961  ****************************************************************/
    00962 ImageIteratorHandle ImageLibIterateImages(UInt16 libRef,
    00963                                           UInt16 category,
    00964                                           UInt16 sortType,
    00965                                           UInt16 *imageCountP,
    00966                                           Err *errP)
    00967     SYS_TRAP(kImageLibTrapIterateImages);
    00968
    00969 /****************************************************************/
    00970 /* ImageLibIterateVFSImages*/
    00971
    00972 /**
    00973  * Creates an iterator for working with a collection of images on a
    00974  * VFS volume. When finished, the iterator refers to a data structure that
    00975  * contains images. The iterator can be used to step through images, draw
    00976  * images, sort images, and search for images by name.
    00977  *
    00978  * The returned iterator handle can be passed to other iterator routines
    00979  * that take an iterator handle. The handle should be freed by calling
    00980  * ImageLibIterFree.
    00981  *
    00982  * @see ImageLibIterFree
    00983  *
    00984  * @param   libRef:         IN:  Library reference number.
    00985  * @param   volRefNum:      IN:  VFS volume to search.
    00986  * @param   path:           IN:  Directory to start searching in.
    00987  * @param   recurseBelow:   IN:  true to recurse in all subdirectories of path. false to search in path only.
    00988  * @param   sortType:       IN:  Initial sort order of the datastructure (kNoSortOrder, kSortByName, or kSortByDate)
    00989  * @param   imageCount:     OUT: Number of images in the iterator data structure. Pass NULL if you don't care about this value.
    00990  * @param   errP:           OUT: 0 on success, non-zero on error. This parameter should not be null.
    00991  * @retval  ImageIteratorHandle Opaque iterator handle.
    00992  *
    00993  ****************************************************************/
    00994 ImageIteratorHandle ImageLibIterateVFSImages(UInt16 libRef,
    00995                                              UInt16 volRefNum,
    00996                                              const char *path,
    00997                                              Boolean recurseBelow,
    00998                                              UInt16 sortType,
    00999                                              UInt16 *imageCount, Err *errP)
    01000     SYS_TRAP(kImageLibTrapIterateVFSImages)  ;
    01001
    01002
    01003 /****************************************************************/
    01004 /* ImageLibIterSort*/
    01005
    01006 /**
    01007  * Sorts the images in an iterator chain. Note that this only reorganizes images
    01008  * in the iterator data structure. This does not alter the way images are stored
    01009  * in the database or on a card.
    01010  * images, sort images, and search for images by name.
    01011  *
    01012  * The iterator handle should be created with ImageLibIterateImages or
    01013  * ImageLibIterateVFSImages.
    01014  *
    01015  * @see ImageLibIterateImages
    01016  * @see ImageLibIterateVFSImages
    01017  *
    01018  * @param   libRef:     IN:  Library reference number.
    01019  * @param   iter:       IN:  Handle to an iterator.
    01020  * @param   sortType:   IN:  New sort order of the datastructure (kNoSortOrder, kSortByName, kSortByDate, kSortByNameDesc, or kSortByDateDesc)
    01021  * @retval  Err 0 on success, non-zero on error.
    01022  *
    01023  ****************************************************************/
    01024 Err ImageLibIterSort (UInt16 libRef,ImageIteratorHandle iter, UInt16 sortType )
    01025     SYS_TRAP(kImageLibTrapIterSort);
    01026
    01027 /****************************************************************/
    01028 /* ImageLibIterGetImageInfo*/
    01029 /**
    01030  * Retrieves information about a single image in an iterator chain.
    01031  *
    01032  * The iterator handle should be created with ImageLibIterateImages or
    01033  * ImageLibIterateVFSImages.
    01034  *
    01035  * Pass NULL for any OUT parameter that you don't care about.
    01036  *
    01037  * @see ImageLibIterateImages
    01038  * @see ImageLibIterateVFSImages
    01039  *
    01040  * @param   libRef:     IN:  Library reference number.
    01041  * @param   iter:       IN:  Handle to an iterator.
    01042  * @param   index:      IN:  Index of the image in the iterator. [0,imageCount)
    01043  * @param   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")
    01044  * @param   nameLen:    IN:  Size in bytes of the name buffer.
    01045  * @param   categoryP:  OUT: Category of the picture if it is stored in the image database. 0xFF if it is a VFS picture.
    01046  * @param   recIndexP:  OUT: Record index of the picture if it is stored in the image database. kInvalidRecIndex if it is a VFS picture.
    01047  * @param   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.
    01048  * @param   createdP:   OUT: Timestamp when picture was creatd. Pass NULL for this parameter if you don't want to retrieve it.
    01049  * @param   sizeP:      OUT: Size of the image data in bytes. Pass NULL for this parameter if you don't want to retrieve it.
    01050  * @param   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.
    01051  * @param   pathLen:    IN:  Size in bytes of the path buffer.
    01052  * @param   lockedP:    OUT: true if the image is locked. False otherwise. VFS images are never locked.
    01053  * @retval  Err 0 on success, non-zero on error.
    01054  *
    01055  ****************************************************************/
    01056 Err ImageLibIterGetImageInfo(UInt16 libRef, ImageIteratorHandle iter,
    01057                              UInt16 index, char *name, UInt16 nameLen,
    01058                              UInt16 *categoryP, UInt16 *recIndexP,
    01059                              UInt16 *volRefNumP, UInt32* createdP,
    01060                              UInt32* sizeP, char *path, UInt16 pathLen,
    01061                              Boolean *lockedP)
    01062     SYS_TRAP(kImageLibTrapIterGetImageInfo)  ;
    01063
    01064
    01065 /****************************************************************/
    01066 /* ImagelibIterGetCount*/
    01067
    01068 /**
    01069  * Retrieves the number of images stored in the iterator data structure.
    01070  *
    01071  * The iterator handle should be created with ImageLibIterateImages or
    01072  * ImageLibIterateVFSImages.
    01073  *
    01074  * Iterator routines that take an index should ensure that the index is
    01075  * less than the value returned in imageCountP.
    01076  *
    01077  * @see ImageLibIterateImages
    01078  * @see ImageLibIterateVFSImages
    01079  *
    01080  * @param   libRef:         IN:  Library reference number.
    01081  * @param   iter:           IN:  Handle to an iterator.
    01082  * @param   imageCountP:    OUT: Number of images in the iterator data structure.
    01083  * @retval  Err 0 on success, non-zero on error.
    01084  *
    01085  ****************************************************************/
    01086 Err ImagelibIterGetCount(UInt16 libRef, ImageIteratorHandle iter,
    01087                          UInt16 *imageCountP)
    01088     SYS_TRAP(kImagelibTrapIterGetCount) ;
    01089
    01090 /****************************************************************/
    01091 /* ImageLibIterDeleteImage*/
    01092
    01093 /**
    01094  * Deletes an image (either from the database or from a VFS volume)
    01095  *
    01096  * Permanently deletes an image given a reference to the image in an iterator.
    01097  * Given an iterator and an index to an image in the iterator, this routine
    01098  * determines whether the image resides in the internal database or on a VFS
    01099  * volume. If it resides on a VFS volume, the routine attempts to delete it by
    01100  * calling VFSFileDelete. If it is an internal image, the picture is nuked by
    01101  * calling ImageLibDeleteImage. After the image is deleted, it is removed from
    01102  * the iterator chain. All subsequent images in the iterator data structure move
    01103  * down one spot. The count of images in the iterator chain is decremented by
    01104  * one.
    01105  *
    01106  * The iterator handle should be created with ImageLibIterateImages or
    01107  * ImageLibIterateVFSImages.
    01108  *
    01109  * Deleting an image invalidates the iterator index for all subsequent
    01110  * images in the iterator chain. If you need to delete a range of images in an
    01111  * iterator, it is best to loop from back to front.
    01112  *
    01113  * @param   libRef:  IN:  Library reference number.
    01114  * @param   iter:    IN:  Handle to an iterator.
    01115  * @param   index:   IN:  Index of the image to delete. This is an index into the iterator, not an index to the image database.
    01116  * @retval  Err 0 on success, non-zero on error.
    01117  *
    01118  ****************************************************************/
    01119 Err ImageLibIterDeleteImage(UInt16 libRef,ImageIteratorHandle iter,
    01120                             UInt16 index)
    01121     SYS_TRAP(kImageLibTrapIterDeleteImage) ;
    01122
    01123 /****************************************************************/
    01124 /* ImageLibIterRemoveImage*/
    01125
    01126 /**
    01127  * Removes an image from an iterator chain without deleting it from its
    01128  * original location.
    01129  *
    01130  * Removes an image from an iterator chain without deleting it from its
    01131  * original location. Once an image is removed, it can no longer be accessed via
    01132  * the iterator. However, the image is still accessible from its original location
    01133  * (either in the image database or on a VFS card).
    01134  *
    01135  * The iterator handle should be created with ImageLibIterateImages or
    01136  * ImageLibIterateVFSImages.
    01137  *
    01138  * Removing an image invalidates the iterator index for all subsequent
    01139  * images in the iterator chain. If you need to remove a range of images in an
    01140  * iterator, it is best to loop from back to front.
    01141  *
    01142  * @param   libRef:  IN:  Library reference number.
    01143  * @param   iter:    IN:  Handle to an iterator.
    01144  * @param   index:   IN:  Index of the image to remove. This is an index into the iterator, not an index to the image database.
    01145  * @retval  Err 0 on success, non-zero on error.
    01146  *
    01147  ****************************************************************/
    01148 Err ImageLibIterRemoveImage(UInt16 libRef, ImageIteratorHandle iter,
    01149                             UInt16 index)
    01150      SYS_TRAP(kImageLibTrapIterRemoveImage) ;
    01151
    01152
    01153 /****************************************************************/
    01154 /* ImageLibIterFree*/
    01155
    01156 /**
    01157  * Frees the memory associated with an iterator chain.
    01158  *
    01159  * The iterator handle should be created with ImageLibIterateImages or
    01160  * ImageLibIterateVFSImages.
    01161  *
    01162  * Once the iterator has been freed, it should not be used anymore.
    01163  *
    01164  * @param   libRef:  IN:  Library reference number.
    01165  * @param   iter:    IN:  Handle to an iterator.
    01166  * @retval  Err 0 on success, non-zero on error.
    01167  *
    01168  ****************************************************************/
    01169 Err ImageLibIterFree (UInt16 libRef, ImageIteratorHandle iter)
    01170     SYS_TRAP(kImageLibTrapIterFree);
    01171
    01172
    01173 /****************************************************************/
    01174 /* ImageLibIterDrawImage*/
    01175
    01176 /**
    01177  * Draws an image in an iterator chain to the current draw window at x,y.
    01178  * x and y are window relative coordinates.
    01179  *
    01180  * If the image resides in the internal database, this routine calls
    01181  * ImageLibImageDraw to draw it. If it is a VFS image the call is dispatched to
    01182  * ImageLibImageDrawFromVFS
    01183  *
    01184  * @param   libRef:  IN:  Library reference number.
    01185  * @param   iter:    IN:  Handle to an iterator.
    01186  * @param   index:   IN:  Index of the image to draw. This is an index into the iterator, not an index to the image database.
    01187  * @param   x:       IN:  x location to draw the preview image, relative to the current draw window.
    01188  * @param   y:       IN:  y location to draw the preview image, relative to the current draw window.
    01189  * @retval  Err 0 on success, non-zero on error.
    01190  *
    01191  ****************************************************************/
    01192 Err ImageLibIterDrawImage(UInt16 libRef, ImageIteratorHandle iter,
    01193                           UInt16 index, Coord x, Coord y)
    01194     SYS_TRAP(kImageLibTrapIterDrawImage);
    01195
    01196
    01197 /****************************************************************/
    01198 /* ImageLibIterDrawThumbnail*/
    01199
    01200 /**
    01201  * Draws a thumbnail for an image in an iterator chain to the current draw
    01202  * window at x,y. x and y are window relative coordinates.
    01203  *
    01204  * If the image resides in the internal database, this routine calls
    01205  * ImageLibThumbnailDraw to draw it. If it is a VFS image the call is dispatched to
    01206  * ImageLibThumbnailDrawFromVFS
    01207  *
    01208  * @param   libRef:  IN:  Library reference number.
    01209  * @param   iter:    IN:  Handle to an iterator.
    01210  * @param   index:   IN:  Index of the image to draw. This is an index into the iterator, not an index to the image database.
    01211  * @param   x:       IN:  x location to draw the preview image, relative to the current draw window.
    01212  * @param   y:       IN:  y location to draw the preview image, relative to the current draw window.
    01213  * @retval  Err 0 on success, non-zero on error.
    01214  *
    01215  ****************************************************************/
    01216 Err ImageLibIterDrawThumbnail (UInt16 libRef, ImageIteratorHandle iter,
    01217                                UInt16 index, Coord x, Coord y)
    01218     SYS_TRAP(kImageLibTrapIterDrawThumbnail);
    01219
    01220 /****************************************************************/
    01221 /* ImageLibIterSearch*/
    01222
    01223 /**
    01224  * Searches for an image in an iterator chain by name. To match, a picture's
    01225  * name must the name string starting in the first character. If partical match
    01226  * is true, then the entire string must match. Case is ignored for all
    01227  * comparisons. Pattern matching and wildcards are not supported.
    01228  *
    01229  * @param   libRef:       IN:  Library reference number.
    01230  * @param   iterH:        IN:  Handle to an iterator.
    01231  * @param   name:         IN:  String to search for.
    01232  * @param   partialMatch: IN:  If true, only the beginning of a picture name must match. If false, the entire name must match.
    01233  * @param   index:        OUT: Contains the index of the first picture that matches the search string. kInvalidRecIndex if no match found.
    01234  * @retval  Err 0 on success, non-zero on error.
    01235  *
    01236  ****************************************************************/
    01237 Err ImageLibIterSearch(UInt16 libRef, ImageIteratorHandle iterH,
    01238                        const char *name, Boolean partialMatch,
    01239                        UInt16 *index)
    01240     SYS_TRAP(kImageLibTrapIterSearch);
    01241
    01242 /****************************************************************/
    01243 /* ImageLibSetProgressCallback*/
    01244
    01245 /**
    01246  * Sets a progress callback function. The image library will invoke this routine
    01247  * periodically during long processing, such as compressing or decompressing a
    01248  * jpeg or resizing an image.
    01249  *
    01250  * All of the APIs that decompress or resize images use the callback
    01251  * mechanism. ImageLibImageSave also invokes it.
    01252  *
    01253  * max is the total number of operations that must be performed. For a JPEG
    01254  * compression or decompression, this equates to the number of horizontal
    01255  * scan lines in the image. The progress value will range from 0 to max.
    01256  * The imaging library will invoked the callback repeatedly. On each pass, the
    01257  * progress variable will increase by some unspecified amount. The operation
    01258  * argument determines the type of operation being performed. Possible values
    01259  * are kResizeOperation, kJPEGOperation, and kVFSOperation.
    01260  *
    01261  * The callback function should have the following signature:
    01262  *
    01263  * @code void callback(Int32 progress, Int32 max, Int8 operation);@endcode
    01264  *
    01265  * @param   libRef:     IN:  Library reference number.
    01266  * @param   callback:   IN:  Address of the callback function. Pass NULL to reset the callback to nothing.
    01267  * @retval  void
    01268  *
    01269  ****************************************************************/
    01270 void ImageLibSetProgressCallback(UInt16 libRef,
    01271                                  ImageLibProgressCallbackType callback)
    01272     SYS_TRAP(kImageLibTrapSetProgressCallback);
    01273
    01274
    01275 /****************************************************************/
    01276 /* ImageLibCopyImage*/
    01277
    01278 /**
    01279  * Creates a copy of an image in the database.
    01280  *
    01281  * @param   libRef:       IN:  Library reference number.
    01282  * @param   recIndex:     IN:  Index of the image to copy.
    01283  * @param   newName:      IN:  Name of the newly copied image.
    01284  * @param   newRecIndexP: OUT: Index of the newly copied image. Pass NULL if you don't care about this value.
    01285  * @retval  Err 0 on success, non-zero on error.
    01286  *
    01287  ****************************************************************/
    01288 Err ImageLibCopyImage(UInt16 libRef, UInt16 recIndex,
    01289                       const char *newName, UInt16 *newRecIndexP)
    01290     SYS_TRAP(kImageLibTrapCopyImage);
    01291
    01292
    01293 /****************************************************************/
    01294 /* ImageLibFindImageByID*/
    01295
    01296 /**
    01297  * Determines the record index of an image in the database given a unique ID.
    01298  * The image is found by calling DmFindRecordByID on the main database.
    01299  *
    01300  * If you need to store a permanent reference to a picture in the
    01301  * database, it is best to store its unique ID. You can obtain the unique ID
    01302  * of an image by calling ImageLibGetImageInfo. To access an image by unique
    01303  * ID, call ImageLibFindImageByID to retrieve the record index, and then use
    01304  * the record index to access the picture.
    01305  *
    01306  * @see ImageLibGetImageInfo
    01307  *
    01308  * @param   libRef:       IN:  Library reference number.
    01309  * @param   uniqueID:     IN:  Unique ID of the image to find.
    01310  * @param   recIndexP:    OUT: Record index of the image.
    01311  * @retval  Err 0 on success, non-zero on error.
    01312  *
    01313  ****************************************************************/
    01314 Err ImageLibFindImageByID (UInt16 libRef, UInt32 uniqueID, UInt16 *recIndexP)
    01315     SYS_TRAP(kImageLibTrapFindImageByID);
    01316
    01317
    01318 /****************************************************************/
    01319 /* ImageLibPreviewStart*/
    01320
    01321 /**
    01322  * Turns on the direct draw preview mode of the camera.
    01323  *
    01324  * This routine serves as a front end to the camera driver's
    01325  * CameraLibPreviewStart function. After being called, the camera will display
    01326  * preview images to the supplied window at the given coordinates.
    01327  *
    01328  * @see ImageLibPreviewStop
    01329  *
    01330  * @param   libRef:       IN:  Library reference number.
    01331  * @param   windowH:      IN:  Window handle where preview images should be drawn. This should generally be a screen window.
    01332  * @param   x:            IN:  x location to draw the preview image. Relative to windowH.
    01333  * @param   y:            IN:  y location to draw the preview image. Relative to windowH.
    01334  * @retval  Err 0 on success, non-zero on error.
    01335  *
    01336  ****************************************************************/
    01337 Err ImageLibPreviewStart (UInt16 libRef, void * windowH, Coord x, Coord y)
    01338     SYS_TRAP(kImageLibTrapPreviewStart);
    01339
    01340 /****************************************************************/
    01341 /* ImageLibPreviewStop*/
    01342
    01343 /**
    01344  * Turns off the direct draw preview mode of the camera.
    01345  *
    01346  * This routine serves as a front end to the camera driver's
    01347  * CameraLibPreviewStop function. It halts previews that were initiated by a
    01348  * call to ImageLibPreviewStart.
    01349  *
    01350  * @see ImageLibPreviewStart
    01351  *
    01352  * @param   libRef:       IN:  Library reference number.
    01353  * @retval  Err 0 on success, non-zero on error.
    01354  *
    01355  ****************************************************************/
    01356 Err ImageLibPreviewStop  (UInt16 libRef)
    01357     SYS_TRAP(kImageLibTrapPreviewStop);
    01358
    01359 /****************************************************************/
    01360 /* ImageLibDrawJPEG*/
    01361
    01362 /**
    01363  * Decompresses a blob of JPEG data and draws it to the current draw window.
    01364  * The picture is drawn at left,top, which are relative to the draw window.
    01365  *
    01366  * If the image needs to be resized, its aspect ratio is maintained. To
    01367  * determine how an image will be resized beforehand, call
    01368  * ImageLibGetDimensionsJPEG.
    01369  *
    01370  * @see ImageLibGetDimensionsJPEG
    01371  *
    01372  * @param   libRef:       IN:  Library reference number.
    01373  * @param   jpegDataP:    IN:  Pointer to a JPEG image in memory.
    01374  * @param   jpegSize:     IN:  Size of the source image in bytes.
    01375  * @param   left:         IN:  x location to draw the image, relative to the current draw window.
    01376  * @param   top:          IN:  y location to draw the image, relative to the current draw window.
    01377  * @param   fitToScreen:  IN:  If true, the JPEG is resized to fit in a box defined by width and height. If false, image is not resized.
    01378  * @param   width:        IN:  Max width of drawn image. Ignored if fitToScreen is false.
    01379  * @param   height:       IN:  Max height of drawn image. Ignored if fitToScreen is false.
    01380  * @retval  Err 0 on success, non-zero on error.
    01381  *
    01382  ****************************************************************/
    01383 Err ImageLibDrawJPEG(UInt16 libRef, MemPtr jpegDataP, UInt32 jpegSize,
    01384                      Coord left, Coord top, Boolean fitToScreen,
    01385                      Coord width, Coord height)
    01386     SYS_TRAP(kImageLibTrapDrawJPEG);
    01387
    01388 /****************************************************************/
    01389 /* ImageLibTurnCameraOff*/
    01390
    01391 /**
    01392  * Deactivates the camera hardware by unloading the camera driver.
    01393  *
    01394  * @param   libRef:       IN:  Library reference number.
    01395  * @retval  Err 0 on success, non-zero on error.
    01396  *
    01397  ****************************************************************/
    01398 Err ImageLibTurnCameraOff(UInt16 libRef)
    01399     SYS_TRAP(kImageLibTrapTurnCameraOff);
    01400
    01401 /****************************************************************/
    01402 /* ImageLibSetImageID*/
    01403
    01404 /**
    01405  * Sets the media and container IDs for an image in the database.
    01406  *
    01407  * The media ID and container ID should both be 21 bytes in size. The image
    01408  * library copies 21 bytes from the supplied buffers into the main record for the
    01409  * image.
    01410  *
    01411  * @see ImageLibGetImageID
    01412  *
    01413  * @param   libRef:         IN:  Library reference number.
    01414  * @param   recIndex:       IN:  Index of image.
    01415  * @param   mediaIDP:       IN:  Media ID.
    01416  * @param   containerIDP:   IN: Container ID.
    01417  * @retval  Err 0 on success, non-zero on error.
    01418  *
    01419  ****************************************************************/
    01420 Err ImageLibSetImageID(UInt16 libRef, UInt16 recIndex,
    01421                       const char* mediaIDP, const char *containerIDP)
    01422     SYS_TRAP(kImageLibTrapSetImageID);
    01423
    01424 /****************************************************************/
    01425 /* ImageLibGetImageID*/
    01426
    01427 /**
    01428  * Gets the media and container IDs for an image in the database.
    01429  *
    01430  * The media ID and container ID should both be at least 21 bytes in size.
    01431  * The library copies 21 bytes to the supplied buffers.
    01432  *
    01433  * @see ImageLibSetImageID
    01434  *
    01435  * @param   libRef:         IN:  Library reference number.
    01436  * @param   recIndex:       IN:  Index of image.
    01437  * @param   mediaIDP:       IN:  Media ID.
    01438  * @param   containerIDP:   IN: Container ID.
    01439  * @retval  Err     0 on success, non-zero on error.
    01440  *
    01441  ****************************************************************/
    01442 Err ImageLibGetImageID(UInt16 libRef, UInt16 recIndex,
    01443                       char* mediaIDP, char *containerIDP)
    01444     SYS_TRAP(kImageLibTrapGetImageID);
    01445
    01446 /****************************************************************/
    01447 /* ImageLibGetDimensions*/
    01448
    01449 /**
    01450  * Retrieves the dimensions of an image in the database.
    01451  *
    01452  * This routine allows clients of the library to query the dimensions of an image
    01453  * in the database. If fitToDimensions is false, the routine copies the full
    01454  * dimensions of the image to widthP and heightP. The initial values of widthP
    01455  * and heightP are ignored. If fitToDimensions is true, the routine calculates
    01456  * how big the image will be after it is downsized to fit in a box determined
    01457  * by the initial values of widthP and heightP.
    01458  *
    01459  * @param   libRef:             IN:  Library reference number.
    01460  * @param   recIndex:           IN:  Index of image.
    01461  * @param   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.
    01462  * @param   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.
    01463  * @param   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.
    01464  * @retval  Err 0 on success, non-zero on error.
    01465  *
    01466  ****************************************************************/
    01467 Err ImageLibGetDimensions     (UInt16 libRef, UInt16 recIndex,
    01468                                Coord *width, Coord *height,
    01469                                Boolean fitToDimensions)
    01470     SYS_TRAP(kImageLibTrapGetDimensions    );
    01471
    01472
    01473 /****************************************************************/
    01474 /* ImageLibGetDimensionsVFS*/
    01475
    01476 /**
    01477  * Retrieves the dimensions of an image on a VFS volume.
    01478  *
    01479  * This routine allows clients of the library to query the dimensions of an image
    01480  * that resides on a VFS volume. The routine follows the same semantics as
    01481  * ImageLibGetDimensions.
    01482  *
    01483  * @see ImageLibGetDimensions
    01484  *
    01485  * @param   libRef:             IN:  Library reference number.
    01486  * @param   volRefNum:          IN:  Ref number of the VFS volume
    01487  * @param   fileName:           IN:  Filename of the image (ie "/DCIM/picture.jpg")
    01488  * @param   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.
    01489  * @param   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.
    01490  * @param   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.
    01491  * @retval  Err 0 on success, non-zero on error.
    01492  *
    01493  ****************************************************************/
    01494 Err ImageLibGetDimensionsVFS  (UInt16 libRef, UInt16 volRefNum,
    01495                                const char* fileName,  Coord *width,
    01496                                Coord *height, Boolean fitToDimensions)
    01497     SYS_TRAP(kImageLibTrapGetDimensionsVFS );
    01498
    01499
    01500 /****************************************************************/
    01501 /* ImageLibIterGetDimensions*/
    01502
    01503 /**
    01504  * Retrieves the dimensions of an image in an iterator chain.
    01505  *
    01506  * This routine allows clients of the library to query the dimensions of an image
    01507  * in an iterator chain. The routine follows the same semantics as
    01508  * ImageLibGetDimensions.
    01509  *
    01510  * @see ImageLibGetDimensions
    01511  *
    01512  * @param   libRef:             IN:  Library reference number.
    01513  * @param   iter:               IN:  Iterator handle
    01514  * @param   index:              IN:  Index of the image in the iterator. [0,imageCount)
    01515  * @param   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.
    01516  * @param   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.
    01517  * @param   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.
    01518  * @retval  Err 0 on success, non-zero on error.
    01519  *
    01520  ****************************************************************/
    01521 Err ImageLibIterGetDimensions (UInt16 libRef, ImageIteratorHandle iter,
    01522                                UInt16 index, Coord *width, Coord *height,
    01523                                Boolean fitToDimensions)
    01524     SYS_TRAP(kImageLibTrapIterGetDimensions);
    01525
    01526
    01527 /****************************************************************/
    01528 /* ImageLibGetDimensionsJPEG*/
    01529
    01530 /**
    01531  * Retrieves the dimensions of a blob of JPEG data in memory.
    01532  *
    01533  * This routine allows clients of the library to query the dimensions of an
    01534  * arbitrary blob of JPEG data. The routine follows the same semantics as
    01535  * ImageLibGetDimensions.
    01536  *
    01537  * @see ImageLibGetDimensions
    01538  *
    01539  * @param   libRef:             IN:  Library reference number.
    01540  * @param   jpegDataP:          IN:  Pointer to a JPEG image in memory.
    01541  * @param   jpegSize:           IN:  Size of the source image in bytes.
    01542  * @param   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.
    01543  * @param   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.
    01544  * @param   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.
    01545  * @retval  Err 0 on success, non-zero on error.
    01546  *
    01547  ****************************************************************/
    01548 Err ImageLibGetDimensionsJPEG (UInt16 libRef, MemPtr jpegDataP, UInt32 jpegSize,
    01549                                Coord *width, Coord *height,
    01550                                Boolean fitToDimensions)
    01551     SYS_TRAP(kImageLibTrapGetDimensionsJPEG);
    01552
    01553
    01554 /****************************************************************/
    01555 /* ImageLibResize*/
    01556
    01557 /**
    01558  * Resizes an image in the database to any arbitrary size.
    01559  *
    01560  * This routine resizes an image in the database to any size. The routine
    01561  * can maintain the existing aspect ratio of the image, or it can stretch it
    01562  * to fit any size.
    01563  *
    01564  * @param   libRef:                 IN:  Library reference number.
    01565  * @param   recIndex:               IN:  Index of image.
    01566  * @param   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.
    01567  * @param   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.
    01568  * @param   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.
    01569  * @retval  Err 0 on success, non-zero on error.
    01570  *
    01571  ****************************************************************/
    01572 Err ImageLibResize (UInt16 libRef, UInt16 recIndex,
    01573                     Coord *widthP, Coord *heightP, Boolean maintainAspectRatio)
    01574     SYS_TRAP(kImageLibTrapResize     );
    01575
    01576 /****************************************************************/
    01577 /* ImageLibResizeVFS*/
    01578
    01579 /**
    01580  * Resizes an image on a VFS volume to any arbitrary size.
    01581  *
    01582  * This routine resizes a VFS image to any size. The routine follows the same
    01583  * semantics as ImageLibResize.
    01584  *
    01585  * @see ImageLibResize
    01586  *
    01587  * @param   libRef:                 IN:  Library reference number.
    01588  * @param   volRefNum:              IN:  Ref number of the VFS volume
    01589  * @param   fileName:               IN:  Filename of the image (ie "/DCIM/picture.jpg")
    01590  * @param   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.
    01591  * @param   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.
    01592  * @param   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.
    01593  * @retval  Err 0 on success, non-zero on error.
    01594  *
    01595  ****************************************************************/
    01596 Err ImageLibResizeVFS(UInt16 libRef, UInt16 volRefNum, const char* fileName,
    01597                       Coord *widthP, Coord *heightP,
    01598                       Boolean maintainAspectRatio)
    01599     SYS_TRAP(kImageLibTrapResizeVFS  );
    01600
    01601
    01602 /****************************************************************/
    01603 /* ImageLibIterResize*/
    01604
    01605 /**
    01606  * Resizes an image in an iterator chain.
    01607  *
    01608  * This routine resizes an image in an iterator chain to any size. The routine
    01609  * follows the same semantics as ImageLibResize.
    01610  *
    01611  * @see ImageLibResize
    01612  *
    01613  * @param   libRef:                 IN:  Library reference number.
    01614  * @param   iter:                   IN:  Iterator handle
    01615  * @param   index:                  IN:  Index of the image in the iterator. [0,imageCount)
    01616  * @param   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.
    01617  * @param   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.
    01618  * @param   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.
    01619  * @retval  Err 0 on success, non-zero on error.
    01620  *
    01621  ****************************************************************/
    01622 Err ImageLibIterResize (UInt16 libRef, ImageIteratorHandle iter, UInt16 index,
    01623                         Coord *widthP, Coord *heightP,
    01624                         Boolean maintainAspectRatio)
    01625     SYS_TRAP(kImageLibTrapIterResize );
    01626
    01627
    01628
    01629 /****************************************************************/
    01630 /* ImageLibResizeJPEG*/
    01631
    01632 /**
    01633  * Resizes a JPEG in memory.
    01634  *
    01635  * This routine resizes a JPEG in memory to any size. The routine
    01636  * follows the same semantics as ImageLibResize, except that it creates a new
    01637  * JPEG in memory as a result.
    01638  *
    01639  * @see ImageLibResize
    01640  *
    01641  * @param   libRef:                 IN:  Library reference number.
    01642  * @param   jpegInputP:             IN:  Pointer to a JPEG image in memory.
    01643  * @param   inputSize:              IN:  Size of the source image in bytes.
    01644  * @param   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.
    01645  * @param   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.
    01646  * @param   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.
    01647  * @param   outputPP:               OUT: Pointer to the newly sized JPEG. The caller is responsible for freeing this memory.
    01648  * @param   outputSizeP:            OUT: Size in bytes of the newly sized JPEG.
    01649  * @retval  Err 0 on success, non-zero on error.
    01650  *
    01651  ****************************************************************/
    01652 Err ImageLibResizeJPEG (UInt16 libRef, MemPtr jpegInputP, UInt32 inputSize,
    01653                         Coord *widthP, Coord *heightP,
    01654                         Boolean maintainAspectRatio, MemPtr *outputPP,
    01655                         UInt32 *outputSizeP)
    01656     SYS_TRAP(kImageLibTrapResizeJPEG);
    01657
    01658
    01659
    01660 /****************************************************************/
    01661 /* ImageLibIterRefresh*/
    01662
    01663 /**
    01664  * Refreshes the information for an image in an iterator chain. If the image is
    01665  * stored in the image database, this routine updates the name, recIndex,
    01666  * category, size, timestamp, and locked status of the image. If it is a VFS
    01667  * picture, this routine updates the timestamp and size of the picture.
    01668  *
    01669  * Call this function when an iterator refers to an image that has changed
    01670  * since the iterator was created. For example, if you downsize or resize an
    01671  * iternal image, call ImageLibIterRefresh to update the iterator information
    01672  * for that image.
    01673  *
    01674  * If you rename a VFS picture that is referenced by an iterator chain, you
    01675  * can pass its new name for the newVFSName argument. Pass the full path and
    01676  * filename of the image. If you pass a string for this argument, the name of
    01677  * file in the iterator chain will be updated. Pass NULL for the newVFSName
    01678  * parameter if the iterator image refers to an internal picture or a VFS
    01679  * picture that whose name has not been changed (If you don't know what this is
    01680  * about, pass NULL).
    01681  *
    01682  * @param   libRef:     IN:  Library reference number.
    01683  * @param   iter:       IN:  Handle to an iterator.
    01684  * @param   index:      IN:  Index of the image in the iterator. [0,imageCount)
    01685  * @param   newVFSName: IN:  If picture is a VFS file, pass its new name for this parameters
    01686  * @retval  Err 0 on success, non-zero on error.
    01687  *
    01688  ****************************************************************/
    01689 Err ImageLibIterRefresh(UInt16 libRef, ImageIteratorHandle iter, UInt16 index,
    01690                         const char *newVFSName)
    01691     SYS_TRAP(kImageLibTrapIterRefresh);
    01692
    01693 /****************************************************************/
    01694 /* ImageLibSetJPEGQuality*/
    01695
    01696 /**
    01697  * Sets the compression factor for all JPEG compression operations performed
    01698  * by the imaging library. The compression factor shoule be a value in the range
    01699  * of 1-99.
    01700  *
    01701  * @param   libRef:       IN:  Library reference number.
    01702  * @param   value:      IN:  new compression quality.
    01703  * @retval  Err 0 on success, non-zero on error.
    01704  *
    01705  ****************************************************************/
    01706 Err ImageLibSetJPEGQuality(UInt16 libRef, Int32 value)
    01707     SYS_TRAP(kImageLibTrapSetJPEGQuality);
    01708
    01709 /****************************************************************/
    01710 /* ImageLibGetJPEGQuality*/
    01711
    01712 /**
    01713  * Returns the compression factor used for JPEG compression operations.
    01714  *
    01715  * @param   libRef:       IN:  Library reference number.
    01716  * @retval  Int32 Compression value. [1,99]
    01717  *
    01718  ****************************************************************/
    01719 Int32 ImageLibGetJPEGQuality(UInt16 libRef)
    01720     SYS_TRAP(kImageLibTrapGetJPEGQuality);
    01721
    01722
    01723
    01724 /****************************************************************/
    01725 /* ImageLibLockImage*/
    01726
    01727 /**
    01728  * Returns the compression factor used for JPEG compression operations.
    01729  *
    01730  * Once an image is locked, it is locked forever and can't be unlocked.
    01731  *
    01732  * @param   libRef:              IN:   Library reference number.
    01733  * @param   recIndex:            IN:   Index of the image to compress.
    01734  * @retval  Err 0 on success, non-zero on error.
    01735  *
    01736  ****************************************************************/
    01737 Err ImageLibLockImage(UInt16 libRef, UInt16 recIndex)
    01738     SYS_TRAP(kImageLibTrapLockImage);
    01739
    01740
    01741 /****************************************************************/
    01742 /* ImageLibGetAveragePictureSize*/
    01743
    01744 /**
    01745  * Returns the average size that a picture will be at the current compression factor.
    01746  *
    01747  * @param   libRef:        IN:   Library reference number.
    01748  * @param   fullsize:      IN:   True to return average of last 20 fullsize captures. False to return average of palm size captures.
    01749  * @retval  Int32 0 Average size.
    01750  *
    01751  ****************************************************************/
    01752 Int32 ImageLibGetAveragePictureSize(UInt16 libRef, Boolean fullsize)
    01753     SYS_TRAP(kImageLibTrapGetAveragePictureSize);
    01754
    01755
    01756 /****************************************************************/
    01757 /* ImageLibCheckLockedImages*/
    01758
    01759 /**
    01760  * Verifies the locked images match the given phone number. If they don't, all locked images
    01761  * are purged from the database.
    01762  *
    01763  * @param libRef:       IN: Library reference number.
    01764  * @param phoneNumber:  IN: String containing the phone number to verify against.
    01765  ****************************************************************/
    01766 void ImageLibCheckLockedImages(UInt16 libRef, const Char *phoneNumber)
    01767     SYS_TRAP(kImageLibTrapCheckLockedImages);
    01768
    01769
    01770 #ifdef __cplusplus
    01771 }
    01772 #endif
    01773
    01774
    01775 #endif

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