1

#ifndef PNGTILE_H

     2

#define PNGTILE_H

     3

     4

/**

     5

 * @file

     6

 *

     7

 * Tile-based access to large PNG images.

     8

 */

     9

#include <stddef.h>

    10

#include <stdio.h> // for FILE*

    11

#include <stdint.h>

    12

#include <sys/types.h> // for time_t

    13

    14

/**

    15

 * "Global" context shared between images

    16

 */

    17

struct pt_ctx;

    18

    19

/**

    20

 * Per-image state

    21

 */

    22

struct pt_image;

    23

    24

/** Bitmask for pt_image_open modes */

    25

enum pt_open_mode {

    26

    /** Update cache if needed */

    27

    PT_OPEN_UPDATE   = 0x01,

    28

    29

    /** Accept stale cache */

    30

    // TODO: PT_OPEN_STALE    = 0x02,

    31

};

    32

    33

/**

    34

 * Values for pt_image_cached

    35

 */

    36

enum pt_cache_status {

    37

    /** Cache status could not be determined */

    38

    PT_CACHE_ERROR      = -1,

    39

    40

    /** Cache is fresh */

    41

    PT_CACHE_FRESH      = 0,

    42

    43

    /** Cache does not exist */

    44

    PT_CACHE_NONE       = 1,

    45

    46

    /** Cache exists, but is stale */

    47

    PT_CACHE_STALE      = 2,

    48

    49

    /** Cache exists, but it was generated using an incompatible version of this library */

    50

    PT_CACHE_INCOMPAT   = 3,

    51

};

    52

    53

/** Metadata info for image. Values will be set to zero if not available */

    54

struct pt_image_info {

    55

    /** Dimensions of image. Only available if the cache is open */

    56

    size_t img_width, img_height;

    57

    58

    /** Bits per pixel */

    59

    size_t img_bpp;

    60

    61

    /** Last update of image file */

    62

    time_t image_mtime;

    63

    64

    /** Size of image file in bytes */

    65

    size_t image_bytes;

    66

    67

    /** Cache format version or -err */

    68

    int cache_version;

    69

    70

    /** Last update of cache file */

    71

    time_t cache_mtime;

    72

    73

    /** Size of cache file in bytes */

    74

    size_t cache_bytes;

    75

    76

    /** Size of cache file in blocks (for sparse cache files) - 512 bytes / block? */

    77

    size_t cache_blocks;

    78

};

    79

    80

/**

    81

 * Modifyable params for update

    82

 */

    83

struct pt_image_params {

    84

    /** Don't write out any contiguous regions of this color. Left-aligned in whatever format the source image is in */

    85

    uint8_t background_color[4];

    86

};

    87

    88

/**

    89

 * Info for image tile 

    90

 *

    91

 * The tile may safely overlap with the edge of the image, but it should not be entirely outside of the image

    92

 */

    93

struct pt_tile_info {

    94

    /** Dimensions of output image */

    95

    size_t width, height;

    96

    97

    /** Pixel coordinates of top-left corner */

    98

    size_t x, y;

    99

   100

    /** Zoom factor of 2^z (out < zero < in) */

   101

    int zoom;

   102

};

   103

   104

/**

   105

 * Construct a new pt_ctx for use with further pt_image's.

   106

 *

   107

 * @param ctx_ptr returned pt_ctx handle

   108

 * @param threads number of worker threads to use for parralel operations, or zero to disable

   109

 */

   110

int pt_ctx_new (struct pt_ctx **ctx_ptr, int threads);

   111

   112

/**

   113

 * Shut down the given pt_ctx, waiting for any ongoing/pending operations to finish.

   114

 */

   115

int pt_ctx_shutdown (struct pt_ctx *ctx);

   116

   117

/**

   118

 * Release the given pt_ctx without waiting for any ongoing operations to finish.

   119

 */

   120

void pt_ctx_destroy (struct pt_ctx *ctx);

   121

   122

/**

   123

 * Open a new pt_image for use.

   124

 *

   125

 * The pt_ctx is optional, but required for pt_image_tile_async.

   126

 *

   127

 * @param img_ptr returned pt_image handle

   128

 * @param ctx global state to use (optional)

   129

 * @param path filesystem path to .png file

   130

 * @param mode combination of PT_OPEN_* flags

   131

 */

   132

int pt_image_open (struct pt_image **image_ptr, struct pt_ctx *ctx, const char *png_path, int cache_mode);

   133

   134

/**

   135

 * Get the image's metadata.

   136

 *

   137

 * XXX: return void, this never fails, just returns partial info

   138

 */

   139

int pt_image_info (struct pt_image *image, const struct pt_image_info **info_ptr);

   140

   141

/**

   142

 * Check the given image's cache is stale - in other words, if the image needs to be update()'d.

   143

 *

   144

 * @return one of pt_cache_status

   145

 */

   146

int pt_image_status (struct pt_image *image);

   147

   148

/**

   149

 * Update the given image's cache.

   150

 *

   151

 * @param params optional parameters to use for the update process

   152

 */

   153

int pt_image_update (struct pt_image *image, const struct pt_image_params *params);

   154

   155

/**

   156

 * Load the image's cache in read-only mode without trying to update it.

   157

 *

   158

 * Fails if the cache doesn't exist.

   159

 */

   160

// XXX: rename to pt_image_open?

   161

int pt_image_load (struct pt_image *image);

   162

   163

/**

   164

 * Render a PNG tile to a FILE*.

   165

 *

   166

 * The PNG data will be written to the given stream, which will be flushed, but not closed.

   167

 */

   168

int pt_image_tile_file (struct pt_image *image, const struct pt_tile_info *info, FILE *out);

   169

   170

/**

   171

 * Render a PNG tile to memory.

   172

 *

   173

 * The PNG data will be written to a malloc'd buffer.

   174

 *

   175

 * @param image render from image's cache

   176

 * @param info tile parameters

   177

 * @param buf_ptr returned heap buffer

   178

 * @param len_ptr returned buffer length

   179

 */

   180

int pt_image_tile_mem (struct pt_image *image, const struct pt_tile_info *info, char **buf_ptr, size_t *len_ptr);

   181

   182

/**

   183

 * Render a PNG tile to FILE* in a parralel manner.

   184

 *

   185

 * The PNG data will be written to \a out, which will be fclose()'d once done.

   186

 *

   187

 * This function may return before the PNG has been rendered.

   188

 *

   189

 * Fails with PT_ERR if not pt_ctx was given to pt_image_open.

   190

 *

   191

 * @param image render from image's cache. The cache must have been opened previously!

   192

 * @param info tile parameters

   193

 * @param out IO stream to write PNG data to, and close once done

   194

 */

   195

int pt_image_tile_async (struct pt_image *image, const struct pt_tile_info *info, FILE *out);

   196

   197

/**

   198

 * Release the given pt_image without any clean shutdown

   199

 */

   200

void pt_image_destroy (struct pt_image *image);

   201

   202

/**

   203

 * Error codes returned

   204

 */

   205

enum pt_error {

   206

    /** No error */

   207

    PT_SUCCESS = 0,

   208

   209

    /** Generic error */

   210

    PT_ERR = 1,

   211

   212

    PT_ERR_MEM,

   213

   214

    PT_ERR_PATH,

   215

    PT_ERR_OPEN_MODE,

   216

   217

    PT_ERR_IMG_STAT,

   220

   221

    PT_ERR_PNG_CREATE,

   222

    PT_ERR_PNG,

   223

   224

    PT_ERR_CACHE_STAT,

   225

    PT_ERR_CACHE_OPEN_READ,

   226

    PT_ERR_CACHE_OPEN_TMP,

   227

    PT_ERR_CACHE_SEEK,

   228

    PT_ERR_CACHE_READ,

   229

    PT_ERR_CACHE_WRITE,

   230

    PT_ERR_CACHE_TRUNC,

   231

    PT_ERR_CACHE_MMAP,

   232

    PT_ERR_CACHE_RENAME_TMP,

   233

    PT_ERR_CACHE_VERSION,

   234

    PT_ERR_CACHE_MUNMAP,

   235

    PT_ERR_CACHE_CLOSE,

   236

   237

    PT_ERR_TILE_CLIP,

   238

   239

    PT_ERR_PTHREAD_CREATE,

   240

    PT_ERR_CTX_SHUTDOWN,

   241

   242

    PT_ERR_ZOOM,

   243

   244

    PT_ERR_MAX,

   245

};

   246

   247

/**

   248

 * Translate error code to short description

   249

 */

   250

const char *pt_strerror (int err);

   251

   252

#endif