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

    12

/**

    13

 * "Global" context shared between images

    14

 */

    15

struct pt_ctx;

    16

    17

/**

    18

 * Per-image state

    19

 */

    20

struct pt_image;

    21

    22

/** Bitmask for pt_image_open modes */

    23

enum pt_open_mode {

    24

    /** Update cache if needed */

    25

    PT_OPEN_UPDATE   = 0x01,

    26

    27

    /** Accept stale cache */

    28

    // TODO: PT_OPEN_STALE    = 0x02,

    29

};

    30

    31

/**

    32

 * Values for pt_image_cached

    33

 */

    34

enum pt_cache_status {

    35

    /** Cache status could not be determined */

    36

    PT_CACHE_ERROR      = -1,

    37

    38

    /** Cache is fresh */

    39

    PT_CACHE_FRESH      = 0,

    40

    41

    /** Cache does not exist */

    42

    PT_CACHE_NONE       = 1,

    43

    44

    /** Cache exists, but is stale */

    45

    PT_CACHE_STALE      = 2,

    46

};

    47

    48

/** Metadata info for image */

    49

struct pt_image_info {

    50

    /** Dimensions of image */

    51

    size_t width, height;

    52

};

    53

    54

/**

    55

 * Info for image tile 

    56

 *

    57

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

    58

 */

    59

struct pt_tile_info {

    60

    /** Dimensions of output image */

    61

    size_t width, height;

    62

    63

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

    64

    size_t x, y;

    65

    66

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

    67

    int zoom;

    68

};

    69

    70

/**

    71

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

    72

 *

    73

 * @param ctx_ptr returned pt_ctx handle

    74

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

    75

 */

    76

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

    77

    78

/**

    79

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

    80

 */

    81

int pt_ctx_shutdown (struct pt_ctx *ctx);

    82

    83

/**

    84

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

    85

 */

    86

void pt_ctx_destroy (struct pt_ctx *ctx);

    87

    88

/**

    89

 * Open a new pt_image for use.

    90

 *

    91

 * @param img_ptr returned pt_image handle

    92

 * @param ctx global state to use

    93

 * @param path filesystem path to .png file

    94

 * @param mode combination of PT_OPEN_* flags

    95

 */

    96

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

    97

    98

/**

    99

 * Get the image's metadata

   100

 */

   101

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

   102

   103

/**

   104

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

   105

 *

   106

 * @return one of pt_cache_status

   107

 */

   108

int pt_image_status (struct pt_image *image);

   109

   110

/**

   111

 * Update the given image's cache.

   112

 */

   113

int pt_image_update (struct pt_image *image);

   114

   115

/**

   116

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

   117

 */

   118

// XXX: rename to pt_image_open?

   119

int pt_image_load (struct pt_image *image);

   120

   121

/**

   122

 * Render a PNG tile to a FILE*.

   123

 *

   124

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

   125

 */

   126

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

   127

   128

/**

   129

 * Render a PNG tile to memory.

   130

 *

   131

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

   132

 *

   133

 * @param image render from image's cache

   134

 * @param info tile parameters

   135

 * @param buf_ptr returned heap buffer

   136

 * @param len_ptr returned buffer length

   137

 */

   138

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

   139

   140

/**

   141

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

   142

 *

   143

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

   144

 *

   145

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

   146

 *

   147

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

   148

 * @param info tile parameters

   149

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

   150

 */

   151

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

   152

   153

/**

   154

 * Release the given pt_image without any clean shutdown

   155

 */

   156

void pt_image_destroy (struct pt_image *image);

   157

   158

/**

   159

 * Error codes returned

   160

 */

   161

enum pt_error {

   162

    PT_SUCCESS = 0,

   163

    PT_ERR_MEM,

   164

   165

    PT_ERR_PATH,

   166

    PT_ERR_OPEN_MODE,

   167

   168

    PT_ERR_IMG_STAT,

   169

    PT_ERR_IMG_FOPEN,

   170

   171

    PT_ERR_PNG_CREATE,

   172

    PT_ERR_PNG,

   173

   174

    PT_ERR_CACHE_STAT,

   175

    PT_ERR_CACHE_OPEN_READ,

   176

    PT_ERR_CACHE_OPEN_TMP,

   177

    PT_ERR_CACHE_SEEK,

   178

    PT_ERR_CACHE_READ,

   179

    PT_ERR_CACHE_WRITE,

   180

    PT_ERR_CACHE_TRUNC,

   181

    PT_ERR_CACHE_MMAP,

   182

    PT_ERR_CACHE_RENAME_TMP,

   183

   184

    PT_ERR_TILE_CLIP,

   185

   186

    PT_ERR_PTHREAD_CREATE,

   187

    PT_ERR_CTX_SHUTDOWN,

   188

   189

    PT_ERR_ZOOM,

   190

   191

    PT_ERR_MAX,

   192

};

   193

   194

/**

   195

 * Translate error code to short description

   196

 */

   197

const char *pt_strerror (int err);

   198

   199

#endif