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>

    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

    51

struct pt_image_info {

    52

    /** Dimensions of image */

    53

    size_t width, height;

    54

    58

    /** Size of image file in bytes */

    59

    size_t image_bytes;

    60

    64

    /** Size of cache file in bytes */

    65

    size_t cache_bytes;

    66

    68

    size_t cache_blocks;

    69

};

    70

    71

/**

    72

 * Modifyable params for update

    73

 */

    74

struct pt_image_params {

    75

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

    76

    uint8_t background_color[4];

    77

};

    78

    79

/**

    80

 * Info for image tile 

    81

 *

    82

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

    83

 */

    84

struct pt_tile_info {

    85

    /** Dimensions of output image */

    86

    size_t width, height;

    87

    88

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

    89

    size_t x, y;

    90

    91

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

    92

    int zoom;

    93

};

    94

    95

/**

    96

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

    97

 *

    98

 * @param ctx_ptr returned pt_ctx handle

    99

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

   100

 */

   101

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

   102

   103

/**

   104

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

   105

 */

   106

int pt_ctx_shutdown (struct pt_ctx *ctx);

   107

   108

/**

   109

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

   110

 */

   111

void pt_ctx_destroy (struct pt_ctx *ctx);

   112

   113

/**

   114

 * Open a new pt_image for use.

   115

 *

   116

 * @param img_ptr returned pt_image handle

   117

 * @param ctx global state to use

   118

 * @param path filesystem path to .png file

   119

 * @param mode combination of PT_OPEN_* flags

   120

 */

   121

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

   122

   123

/**

   124

 * Get the image's metadata

   125

 */

   126

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

   127

   128

/**

   129

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

   130

 *

   131

 * @return one of pt_cache_status

   132

 */

   133

int pt_image_status (struct pt_image *image);

   134

   135

/**

   136

 * Update the given image's cache.

   137

 *

   138

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

   139

 */

   140

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

   141

   142

/**

   143

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

   144

 */

   145

// XXX: rename to pt_image_open?

   146

int pt_image_load (struct pt_image *image);

   147

   148

/**

   149

 * Render a PNG tile to a FILE*.

   150

 *

   151

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

   152

 */

   153

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

   154

   155

/**

   156

 * Render a PNG tile to memory.

   157

 *

   158

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

   159

 *

   160

 * @param image render from image's cache

   161

 * @param info tile parameters

   162

 * @param buf_ptr returned heap buffer

   163

 * @param len_ptr returned buffer length

   164

 */

   165

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

   166

   167

/**

   168

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

   169

 *

   170

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

   171

 *

   172

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

   173

 *

   174

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

   175

 * @param info tile parameters

   176

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

   177

 */

   178

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

   179

   180

/**

   181

 * Release the given pt_image without any clean shutdown

   182

 */

   183

void pt_image_destroy (struct pt_image *image);

   184

   185

/**

   186

 * Error codes returned

   187

 */

   188

enum pt_error {

   189

    PT_SUCCESS = 0,

   190

    PT_ERR_MEM,

   191

   192

    PT_ERR_PATH,

   193

    PT_ERR_OPEN_MODE,

   194

   195

    PT_ERR_IMG_STAT,

   196

    PT_ERR_IMG_FOPEN,

   197

   198

    PT_ERR_PNG_CREATE,

   199

    PT_ERR_PNG,

   200

   201

    PT_ERR_CACHE_STAT,

   202

    PT_ERR_CACHE_OPEN_READ,

   203

    PT_ERR_CACHE_OPEN_TMP,

   204

    PT_ERR_CACHE_SEEK,

   205

    PT_ERR_CACHE_READ,

   206

    PT_ERR_CACHE_WRITE,

   207

    PT_ERR_CACHE_TRUNC,

   208

    PT_ERR_CACHE_MMAP,

   209

    PT_ERR_CACHE_RENAME_TMP,

   210

   211

    PT_ERR_TILE_CLIP,

   212

   213

    PT_ERR_PTHREAD_CREATE,

   214

    PT_ERR_CTX_SHUTDOWN,

   215

   216

    PT_ERR_ZOOM,

   217

   218

    PT_ERR_MAX,

   219

};

   220

   221

/**

   222

 * Translate error code to short description

   223

 */

   224

const char *pt_strerror (int err);

   225

   226

#endif