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 */

    24

    /** Update cache if needed */

    25

    PT_OPEN_UPDATE   = 0x01,

    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

/**

    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 (out < zero < in) */

    67

    // TODO: int zoom;

    68

};

    69

    70

/**

    71

 * TODO: impl

    72

 */

    73

int pt_ctx_new (struct pt_ctx **ctx_ptr);

    74

    75

/**

    76

 * Open a new pt_image for use.

    77

 *

    78

 * @param img_ptr returned pt_image handle

    79

 * @param ctx global state to use

    80

 * @param path filesystem path to .png file

    81

 * @param mode combination of PT_OPEN_* flags

    82

 */

    83

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

    84

    85

/**

    86

 * Get the image's metadata

    87

 */

    88

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

    89

    90

/**

    91

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

    92

 *

    93

 * @return one of pt_cache_status

    94

 */

    95

int pt_image_status (struct pt_image *image);

    96

    97

/**

    98

 * Update the given image's cache.

    99

 */

   100

int pt_image_update (struct pt_image *image);

   101

   102

/**

   103

 * Render a PNG tile to a stream.

   104

 *

   105

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

   106

 */

   107

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

   108

   109

/**

   110

 * Release the given pt_image without any clean shutdown

   111

 */

   112

void pt_image_destroy (struct pt_image *image);

   113

   114

#endif