| |
 |  | |  | |  | |  | |  | |
 |
| |
File LayerReading PhotoJazz Files Since BitJazz is a shared library, your product cannot count on its existence. Before trying to read a PhotoJazz file, you should check whether PhotoJazz was successfully linked in. On the Power Macintosh, you can do this by testing the address of one of the interface functions: if (!&JzReadBegin){ To read a PhotoJazz file, you call three functions: JzReadBegin to begin reading, JzReadTile to read each tile, and JzReadEnd to end reading. JzReadBegin passes back a JzFile pointer which you pass back as the first argument to the other JzRead functions and to all JzGet functions. JzStreamResult JzReadBegin(JzStream *aStream, JzAllocator *aAllocator, JzInterpreter *aInterpreter, JzYielder *aYielder, JzKey aProduct, JzFile **aJazzFile); If you just want to scan the PhotoJazz file without retrieving the image data, you can call JzSkipTile instead of JzReadTile: JzStreamResult JzSkipTile(JzFile *aJazzFile); All four of these functions return a JzStreamResult to indicate either success (kJzStreamResultOkay) or some kind of error. If JzReadTile or JzSkipTile returns an error, you must still call JzReadEnd to allow PhotoJazz to clean up properly. Several of the result values always indicate errors in your use of the PhotoJazz interface. The result kJzStreamResultMissingArgument indicates that you passed in a NULL pointer for a required argument; kJzStreamResultIncompleteArgument means that you failed to assign a pointer to one of the members of a required argument; kJzStreamResultInconsistentArgument means that the value of an argument you specified is inconsistent with the current state. Three such errors are passed through from your JzStream mRead callback function. Thus kJzStreamResultInvalidFileID means that the operating-system-specific file number you supplied is invalid; kJzStreamResultNotOpen means that you forgot to open the file before having PhotoJazz read from it, or closed the file before PhotoJazz was done reading from it. kJzStreamResultMissingArgument, //NULL address Several other result values sometimes indicate an error in your use of the PhotoJazz interface. The result kJzStreamResultInvalidSerialNumber may refer to either your product key or the user's key; kJzStreamResultOutsideFile means that you positioned the stream before the beginning of the file, or, more commonly, that you attempted to read more tiles than there are in the image, which could be due to a truncated, corrupted PhotoJazz file; kJzStreamResultUnreadable could mean either that you are trying to read from a file that you opened for write access, or (when passed through from your JzStream mRead function) that the file itself is on a write-only or inaccessible volume; kJzStreamResultUnimplemented could mean either that you are specifying an invalid argument (typically enum) value, or that your PhotoJazz engine needs to be updated to a newer version. kJzStreamResultInvalidSerialNumber, //bad user key or product key To begin reading a PhotoJazz file, you create four C objects: a JzStream (aStream) to let PhotoJazz read data from the file, a JzAllocator (aAllocator) to allocate memory for PhotoJazz, a JzInterpreter (aInterpreter) to interpret private data chunks, and a JzYielder (aYielder) to let PhotoJazz yield time to other tasks. All four of these objects are required arguments. The stream must already be open and positioned at the beginning of the PhotoJazz file before calling JzReadBegin. You must also pass in a JzKey (aProduct) for the product. For now, pass in the default key, kJzWatermarkProduct, which applies a watermark to all images you write. When your product has advanced to the stage where you need to test without watermarking, contact us for a commercial key for your product, which we supply free of charge under the terms of our developer license agreement. In its last argument, JzReadBegin passes back an opaque JzFile pointer (aJazzFile) which you supply as the first argument in all subsequent JzRead and JzGet calls for this image. As its function result, JzReadBegin returns a JzStreamResult. A result of kJzStreamResultOkay indicates success; Any other result indicates an error. If an error occurs during JzReadBegin, JzReadBegin cleans up and passes back a NULL pointer for the JzFile. JzStreamResult JzReadBegin(JzStream *aStream, JzAllocator *aAllocator, JzInterpreter *aInterpreter, JzYielder *aYielder, JzKey aProduct, JzFile **aJazzFile); In addition to allocating and initializing a JzFile structure, JzReadBegin reads the file identifier and safety bits and all the parameters up to (but excluding) the first tile in the Photojazz file. To read the next tile from a PhotoJazz file, you call JzReadTile, passing it the JzFile pointer (aJazzFile) given you by JzReadBegin; the width (aRowWidth) of the tile buffer in pixels (not in bytes!), and the address (aImage) of the tile buffer. JzStreamResult JzReadTile(JzFile *aJazzFile, unsigned long aRowWidth, void *aImage); If you need all the channels of all the tiles in the image, then read the image directly into your image buffer; otherwise, read each tile into an intermediate tile buffer. As its function result, JzReadTile returns a JzStreamResult. A result of kJzStreamResultOkay indicates success; Any other result indicates an error. If an error occurs, you must still call JzReadEnd to let PhotoJazz clean up properly. JzReadTile reads and decompresses the tile at which the stream is positioned, and then immediately reads all parameters up to (but excluding) the next tile, if any, in the PhotoJazz file. If this was the last tile, it reads all the parameters up to the end of the file. Thus the parameter values after reading a tile refer to the next tile (if any), not to the tile just read. To skip over the next tile in a PhotoJazz file, you call JzSkipTile, passing it the JzFile pointer (aJazzFile) given you by JzReadBegin. JzStreamResult JzSkipTile(JzFile *aJazzFile); As its function result, JzSkipTile returns a JzStreamResult. A result of kJzStreamResultOkay indicates success; Any other result indicates an error. If an error occurs, you must still call JzReadEnd to let PhotoJazz clean up properly. JzSkipTile reads the tile at which the stream is positioned, verifies the integrity of the tile data and then discards it, and then immediately reads all parameters up to (but excluding) the next tile, if any, in the PhotoJazz file. If this was the last tile, it reads all the parameters up to the end of the file. Thus the parameter values after reading a tile refer to the next tile (if any), not to the tile just skipped. After you have read all the tiles from a PhotoJazz image file, or if an error has occurred while reading and processing the tiles, you must call JzReadEnd. JzReadEnd only takes one argument, the JzFile pointer (aJazzFile) passed back by JzReadBegin. JzStreamResult JzReadEnd(JzFile *aJazzFile); Once you have called JzReadEnd, the JzFile pointer is no longer valid, so it is advisable to set it to zero for defensive programming. If the JzStream you passed in to JzReadBegin needs to be closed, this is the time to do it. JzReadEnd frees all the remaining buffers that PhotoJazz has allocated for the file. Examples Here is a code snippet of a JzRead sequence that reads an entire PhotoJazz image into an image buffer:unsigned char lChannelCount;error: The variables lStream, lAllocator, lInterpreter, and lYielder are defined and initialized by you prior to this code snippet.
|
|
PhotoJazz API Manual