terom@0: #ifndef PNGTILE_H
terom@0: #define PNGTILE_H
terom@0: 
terom@0: /**
terom@0:  * @file
terom@0:  *
terom@0:  * Tile-based access to large PNG images.
terom@0:  */
terom@6: #include <stddef.h>
terom@9: #include <stdio.h> // for FILE*
terom@52: #include <stdint.h>
terom@54: #include <sys/types.h> // for time_t
terom@0: 
terom@0: /**
terom@0:  * "Global" context shared between images
terom@0:  */
terom@0: struct pt_ctx;
terom@0: 
terom@0: /**
terom@0:  * Per-image state
terom@0:  */
terom@0: struct pt_image;
terom@0: 
terom@6: /** Bitmask for pt_image_open modes */
terom@15: enum pt_open_mode {
terom@80:     /** Open cache for read*/
terom@80:     PT_OPEN_READ    = 0x00,
terom@80: 
terom@80:     /** Open cache for update */
terom@11:     PT_OPEN_UPDATE   = 0x01,
terom@6: 
terom@6:     /** Accept stale cache */
terom@15:     // TODO: PT_OPEN_STALE    = 0x02,
terom@6: };
terom@6: 
terom@8: /**
terom@8:  * Values for pt_image_cached
terom@8:  */
terom@8: enum pt_cache_status {
terom@8:     /** Cache status could not be determined */
terom@8:     PT_CACHE_ERROR      = -1,
terom@8:     
terom@8:     /** Cache is fresh */
terom@8:     PT_CACHE_FRESH      = 0,
terom@8: 
terom@8:     /** Cache does not exist */
terom@8:     PT_CACHE_NONE       = 1,
terom@8: 
terom@8:     /** Cache exists, but is stale */
terom@8:     PT_CACHE_STALE      = 2,
terom@56: 
terom@56:     /** Cache exists, but it was generated using an incompatible version of this library */
terom@56:     PT_CACHE_INCOMPAT   = 3,
terom@8: };
terom@8: 
terom@54: /** Metadata info for image. Values will be set to zero if not available */
terom@6: struct pt_image_info {
terom@56:     /** Dimensions of image. Only available if the cache is open */
terom@56:     size_t img_width, img_height;
terom@56: 
terom@56:     /** Bits per pixel */
terom@56:     size_t img_bpp;
terom@53: 
terom@54:     /** Last update of image file */
terom@54:     time_t image_mtime;
terom@54: 
terom@53:     /** Size of image file in bytes */
terom@53:     size_t image_bytes;
terom@56:     
terom@56:     /** Cache format version or -err */
terom@56:     int cache_version;
terom@53: 
terom@54:     /** Last update of cache file */
terom@54:     time_t cache_mtime;
terom@54: 
terom@53:     /** Size of cache file in bytes */
terom@53:     size_t cache_bytes;
terom@53: 
terom@54:     /** Size of cache file in blocks (for sparse cache files) - 512 bytes / block? */
terom@53:     size_t cache_blocks;
terom@0: };
terom@0: 
terom@13: /**
terom@52:  * Modifyable params for update
terom@52:  */
terom@52: struct pt_image_params {
terom@52:     /** Don't write out any contiguous regions of this color. Left-aligned in whatever format the source image is in */
terom@52:     uint8_t background_color[4];
terom@52: };
terom@52: 
terom@52: /**
terom@13:  * Info for image tile 
terom@13:  *
terom@13:  * The tile may safely overlap with the edge of the image, but it should not be entirely outside of the image
terom@13:  */
terom@9: struct pt_tile_info {
terom@9:     /** Dimensions of output image */
terom@9:     size_t width, height;
terom@9: 
terom@9:     /** Pixel coordinates of top-left corner */
terom@9:     size_t x, y;
terom@9: 
terom@34:     /** Zoom factor of 2^z (out < zero < in) */
terom@34:     int zoom;
terom@9: };
terom@9: 
terom@11: /**
terom@19:  * Construct a new pt_ctx for use with further pt_image's.
terom@19:  *
terom@19:  * @param ctx_ptr returned pt_ctx handle
terom@19:  * @param threads number of worker threads to use for parralel operations, or zero to disable
terom@11:  */
terom@19: int pt_ctx_new (struct pt_ctx **ctx_ptr, int threads);
terom@19: 
terom@19: /**
terom@19:  * Shut down the given pt_ctx, waiting for any ongoing/pending operations to finish.
terom@19:  */
terom@19: int pt_ctx_shutdown (struct pt_ctx *ctx);
terom@19: 
terom@19: /**
terom@19:  * Release the given pt_ctx without waiting for any ongoing operations to finish.
terom@19:  */
terom@19: void pt_ctx_destroy (struct pt_ctx *ctx);
terom@0: 
terom@0: /**
terom@0:  * Open a new pt_image for use.
terom@0:  *
terom@64:  * The pt_ctx is optional, but required for pt_image_tile_async.
terom@64:  *
terom@0:  * @param img_ptr returned pt_image handle
terom@64:  * @param ctx global state to use (optional)
terom@0:  * @param path filesystem path to .png file
terom@11:  * @param mode combination of PT_OPEN_* flags
terom@0:  */
terom@5: int pt_image_open (struct pt_image **image_ptr, struct pt_ctx *ctx, const char *png_path, int cache_mode);
terom@0: 
terom@5: /**
terom@56:  * Get the image's metadata.
terom@56:  *
terom@56:  * XXX: return void, this never fails, just returns partial info
terom@6:  */
terom@7: int pt_image_info (struct pt_image *image, const struct pt_image_info **info_ptr);
terom@6: 
terom@6: /**
terom@8:  * Check the given image's cache is stale - in other words, if the image needs to be update()'d.
terom@8:  *
terom@8:  * @return one of pt_cache_status
terom@5:  */
terom@8: int pt_image_status (struct pt_image *image);
terom@0: 
terom@5: /**
terom@5:  * Update the given image's cache.
terom@52:  *
terom@52:  * @param params optional parameters to use for the update process
terom@5:  */
terom@52: int pt_image_update (struct pt_image *image, const struct pt_image_params *params);
terom@0: 
terom@6: /**
terom@19:  * Load the image's cache in read-only mode without trying to update it.
terom@56:  *
terom@56:  * Fails if the cache doesn't exist.
terom@19:  */
terom@19: // XXX: rename to pt_image_open?
terom@25: int pt_image_load (struct pt_image *image);
terom@19: 
terom@19: /**
terom@18:  * Render a PNG tile to a FILE*.
terom@9:  *
terom@9:  * The PNG data will be written to the given stream, which will be flushed, but not closed.
terom@91:  *
terom@91:  * Tile render operations are threadsafe as long as the pt_image is not modified during execution.
terom@9:  */
terom@18: int pt_image_tile_file (struct pt_image *image, const struct pt_tile_info *info, FILE *out);
terom@18: 
terom@18: /**
terom@18:  * Render a PNG tile to memory.
terom@18:  *
terom@18:  * The PNG data will be written to a malloc'd buffer.
terom@18:  *
terom@91:  * Tile render operations are threadsafe as long as the pt_image is not modified during execution.
terom@91:  *
terom@18:  * @param image render from image's cache
terom@18:  * @param info tile parameters
terom@18:  * @param buf_ptr returned heap buffer
terom@18:  * @param len_ptr returned buffer length
terom@18:  */
terom@18: int pt_image_tile_mem (struct pt_image *image, const struct pt_tile_info *info, char **buf_ptr, size_t *len_ptr);
terom@9: 
terom@9: /**
terom@19:  * Render a PNG tile to FILE* in a parralel manner.
terom@19:  *
terom@19:  * The PNG data will be written to \a out, which will be fclose()'d once done.
terom@19:  *
terom@19:  * This function may return before the PNG has been rendered.
terom@19:  *
terom@64:  * Fails with PT_ERR if not pt_ctx was given to pt_image_open.
terom@64:  *
terom@19:  * @param image render from image's cache. The cache must have been opened previously!
terom@19:  * @param info tile parameters
terom@19:  * @param out IO stream to write PNG data to, and close once done
terom@19:  */
terom@19: int pt_image_tile_async (struct pt_image *image, const struct pt_tile_info *info, FILE *out);
terom@19: 
terom@19: /**
terom@6:  * Release the given pt_image without any clean shutdown
terom@6:  */
terom@6: void pt_image_destroy (struct pt_image *image);
terom@6: 
terom@17: /**
terom@17:  * Error codes returned
terom@17:  */
terom@17: enum pt_error {
terom@64:     /** No error */
terom@17:     PT_SUCCESS = 0,
terom@64:     
terom@64:     /** Generic error */
terom@64:     PT_ERR = 1,
terom@64: 
terom@17:     PT_ERR_MEM,
terom@17: 
terom@17:     PT_ERR_PATH,
terom@17:     PT_ERR_OPEN_MODE,
terom@17:     
terom@17:     PT_ERR_IMG_STAT,
terom@69:     PT_ERR_IMG_OPEN,
terom@69:     PT_ERR_IMG_FORMAT,
terom@17:     
terom@17:     PT_ERR_PNG_CREATE,
terom@17:     PT_ERR_PNG,
terom@17:    
terom@17:     PT_ERR_CACHE_STAT,
terom@17:     PT_ERR_CACHE_OPEN_READ,
terom@17:     PT_ERR_CACHE_OPEN_TMP,
terom@17:     PT_ERR_CACHE_SEEK,
terom@17:     PT_ERR_CACHE_READ,
terom@17:     PT_ERR_CACHE_WRITE,
terom@17:     PT_ERR_CACHE_TRUNC,
terom@17:     PT_ERR_CACHE_MMAP,
terom@17:     PT_ERR_CACHE_RENAME_TMP,
terom@56:     PT_ERR_CACHE_VERSION,
terom@59:     PT_ERR_CACHE_MUNMAP,
terom@59:     PT_ERR_CACHE_CLOSE,
terom@86:     
terom@86:     PT_ERR_TILE_DIM,
terom@17:     PT_ERR_TILE_CLIP,
terom@86:     PT_ERR_TILE_ZOOM,
terom@17: 
terom@19:     PT_ERR_PTHREAD_CREATE,
terom@19:     PT_ERR_CTX_SHUTDOWN,
terom@19: 
terom@34: 
terom@17:     PT_ERR_MAX,
terom@17: };
terom@17: 
terom@17: /**
terom@17:  * Translate error code to short description
terom@17:  */
terom@17: const char *pt_strerror (int err);
terom@17: 
terom@0: #endif