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_image_mode {

    24

    /** Update cache if needed */

    26

    27

    /** Accept stale cache */

    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

/** Info for image tile */

    55

struct pt_tile_info {

    56

    /** Dimensions of output image */

    57

    size_t width, height;

    58

    59

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

    60

    size_t x, y;

    61

    62

    /** Zoom factor (out < zero < in) */

    63

    // TODO: int zoom;

    64

};

    65

    69

int pt_ctx_new (struct pt_ctx **ctx_ptr);

    70

    71

/**

    72

 * Open a new pt_image for use.

    73

 *

    74

 * @param img_ptr returned pt_image handle

    75

 * @param ctx global state to use

    76

 * @param path filesystem path to .png file

    78

 */

    79

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

    80

    81

/**

    82

 * Get the image's metadata

    83

 */

    84

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

    85

    86

/**

    87

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

    88

 *

    89

 * @return one of pt_cache_status

    90

 */

    91

int pt_image_status (struct pt_image *image);

    92

    93

/**

    94

 * Update the given image's cache.

    95

 */

    96

int pt_image_update (struct pt_image *image);

    97

    98

/**

    99

 * Render a PNG tile to a stream.

   100

 *

   101

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

   102

 */

   103

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

   104

   105

/**

   106

 * Release the given pt_image without any clean shutdown

   107

 */

   108

void pt_image_destroy (struct pt_image *image);

   109

   110

#endif