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@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@0: enum pt_image_mode {
terom@6:     /** Update cache if needed */
terom@6:     PT_IMG_WRITE    = 0x01,
terom@6: 
terom@6:     /** Accept stale cache */
terom@6:     PT_IMG_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@8: };
terom@8: 
terom@6: /** Metadata info for image */
terom@6: struct pt_image_info {
terom@6:     /** Dimensions of image */
terom@7:     size_t width, height;
terom@0: };
terom@0: 
terom@0: 
terom@0: int pt_ctx_new (struct pt_ctx **ctx_ptr);
terom@0: 
terom@0: /**
terom@0:  * Open a new pt_image for use.
terom@0:  *
terom@0:  * @param img_ptr returned pt_image handle
terom@0:  * @param ctx global state to use
terom@0:  * @param path filesystem path to .png file
terom@0:  * @param mode combination of PT_IMG_* 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@6:  * Get the image's metadata
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@5:  */
terom@5: int pt_image_update (struct pt_image *image);
terom@0: 
terom@6: /**
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@0: #endif