doc/loaders.txt

   1 Context loaders
   2 ---------------
   3 This part of gfxprim library aims to create API to load/save images from/to
   4 common image file formats.
   5
   6 All loading functions returns a pointer to allocated and loaded image or upon
   7 a failure 'NULL' is returned and 'errno' is set.
   8
   9 The possible errno values are:
  10
  11 * anything returned by fopen(), fclose(), fseek(), ...
  12 * 'ENOSYS' if library wasn't compiled with particular library support
  13 * 'ENOMEM' as returned by malloc()
  14 * 'EIO'/'EILSEQ' invalid image data
  15 * 'ECANCELED' loading canceled from callback
  16
  17 Common Loader
  18 ~~~~~~~~~~~~~
  19
  20 [source,c]
  21 -------------------------------------------------------------------------------
  22 #include <loaders/GP_Loaders.h>
  23 /* or */
  24 #include <GP.h>
  25
  26 GP_Context *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback);
  27 -------------------------------------------------------------------------------
  28
  29 Loads image from a file. The format is now matched by an image file extension.
  30 File signature loading method is on the TODO.
  31
  32 [source,c]
  33 -------------------------------------------------------------------------------
  34 #include <loaders/GP_Loaders.h>
  35 /* or */
  36 #include <GP.h>
  37
  38 int GP_SaveImage(GP_Context *src, const char *dst_path,
  39                  GP_ProgressCallback *callback);
  40 -------------------------------------------------------------------------------
  41
  42 Saves a context into a file. The file format is matched accordingly to the
  43 file extension, if extension is invalid or if support for requested image
  44 format wasn't compiled in, non-zero is returned and 'errno' is set to
  45 'ENOSYS'.
  46
  47 Returns zero on success and non-zero on failure and 'errno' is set. The
  48 possible errno values are 'ENOSYS' for unknown format and anything that could
  49 be returned by 'fopen()', 'open()', 'fwrite()', 'write()', 'seek()', etc...
  50
  51 PNG
  52 ~~~
  53 The 'PNG' loading support is optionally implemented by libpng.
  54
  55 Just now, the 'PNG' support is not fully finished. Images with alpha channel
  56 are not supported yet.
  57
  58 [source,c]
  59 -------------------------------------------------------------------------------
  60 #include <loaders/GP_PNG.h>
  61 /* or */
  62 #include <GP.h>
  63
  64 int GP_OpenPNG(const char *src_path, FILE **f);
  65 -------------------------------------------------------------------------------
  66
  67 Opens file and checks for 'PNG' signature.  Returns zero on success (file
  68 could be opened, signature matches), the opened file is returned and the file
  69 position points right after the end of the 'PNG' signature.
  70
  71 Upon failure 'errno' is filled.
  72
  73 This function is semi-internal, you should rather use functions listed below.
  74
  75 [source,c]
  76 -------------------------------------------------------------------------------
  77 #include <loaders/GP_PNG.h>
  78 /* or */
  79 #include <GP.h>
  80
  81 GP_Context *GP_ReadPNG(FILE *f, GP_ProgressCallback *callback);
  82 -------------------------------------------------------------------------------
  83
  84 Loads 'PNG' file into context the file pointer must point to the start of the
  85 'PNG' data stream (i.e. should point right after the signature). The context,
  86 to store the image to, is allocated. The loading process could by aborted by a
  87 callback, in such case all memory is freed.
  88
  89 [source,c]
  90 -------------------------------------------------------------------------------
  91 #include <loaders/GP_PNG.h>
  92 /* or */
  93 #include <GP.h>
  94
  95 GP_Context *GP_LoadPNG(const char *src_path, GP_ProgressCallback *callback);
  96 -------------------------------------------------------------------------------
  97
  98 Same as above but takes path to the file as a parameter and check for the
  99 signature. Basically this combines both of the calls above.
 100
 101 [source,c]
 102 -------------------------------------------------------------------------------
 103 #include <loaders/GP_PNG.h>
 104 /* or */
 105 #include <GP.h>
 106
 107 int GP_SavePNG(const GP_Context *src, const char *dst_path,
 108                GP_ProgressCallback *callback);
 109 -------------------------------------------------------------------------------
 110
 111 Writes a Context into a 'PNG' image. If aborted by a callback, the opened file
 112 is closed and removed before the call returns non-zero and 'errno' is set to
 113 'ECANCELED'.
 114
 115 Currently only 'RGB888' format is supported, you should convert the
 116 'GP_Context' to 'RGB888' before calling this function otherwise non-zero is
 117 returned and 'errno' is set to 'ENOSYS'.
 118
 119 JPEG
 120 ~~~~
 121 The 'JPEG' loading support is optionally implemented by jpeg library.
 122
 123 [source,c]
 124 -------------------------------------------------------------------------------
 125 #include <loaders/GP_JPG.h>
 126 /* or */
 127 #include <GP.h>
 128
 129 int GP_OpenJPG(const char *src_path, FILE **f);
 130 -------------------------------------------------------------------------------
 131
 132 Opens file and checks for 'JPG' signature upon successful return (file could
 133 be opened, signature matches), the opened file is returned and the file
 134 position points right after the end of the 'JPG' signature.
 135
 136 This function is semi-internal, you should rather use functions listed below.
 137
 138 'TODO:' This is not finished yet, currently this just opens and returns the
 139 file and the 'GP_ReadJPG()' reads the signature instead.
 140
 141 [source,c]
 142 -------------------------------------------------------------------------------
 143 #include <loaders/GP_JPG.h>
 144 /* or */
 145 #include <GP.h>
 146
 147 GP_Context *GP_ReadJPG(FILE *f, GP_ProgressCallback *callback);
 148 -------------------------------------------------------------------------------
 149
 150 Loads 'JPG' file into context the file pointer must point to the start of the
 151 'JPG' data stream (i.e. should point right after the signature). The context,
 152 to store the image to, is allocated. The loading process could by aborted by a
 153 callback, in such case all memory is freed and the call returns 'NULL' and
 154 'errno' is set to 'ECANCELED'.
 155
 156 [source,c]
 157 -------------------------------------------------------------------------------
 158 #include <loaders/GP_JPG.h>
 159 /* or */
 160 #include <GP.h>
 161
 162 GP_Context *GP_LoadJPG(const char *src_path, GP_ProgressCallback *callback);
 163 -------------------------------------------------------------------------------
 164
 165 Same as above but takes path to the file as a parameter and check for the
 166 signature. Basically this combines both of the calls above.
 167
 168 [source,c]
 169 -------------------------------------------------------------------------------
 170 #include <loaders/GP_JPG.h>
 171 /* or */
 172 #include <GP.h>
 173
 174 int GP_SaveJPG(const GP_Context *src, const char *dst_path,
 175                GP_ProgressCallback *callback);
 176 -------------------------------------------------------------------------------
 177
 178 Writes a Context into a 'JPG' image. If aborted by a callback, the opened file
 179 is closed and removed before the call returns non-zero and 'errno' is set to
 180 'ECANCELED'.
 181
 182 The 'JPG' format could store either 'G8' or 'RGB888' pixeltypes and you must
 183 convert the context into one of them before this functions is called.
 184
 185 GIF
 186 ~~~
 187
 188 The 'GIF' format is supported optionally by giflib library.
 189
 190 [source,c]
 191 -------------------------------------------------------------------------------
 192 #include <loaders/GP_GIF.h>
 193 /* or */
 194 #include <GP.h>
 195
 196 int GP_OpenGIF(const char *src_path, void **f);
 197 -------------------------------------------------------------------------------
 198
 199 Opens file and checks for 'GIF' signature upon successful return (file could
 200 be opened, signature matches) zero is returned and gif handle f is set
 201 otherwise non-zero is returned and 'errno' is set.
 202
 203 This function is semi-internal, you should rather use functions listed below.
 204
 205 [source,c]
 206 -------------------------------------------------------------------------------
 207 #include <loaders/GP_GIF.h>
 208 /* or */
 209 #include <GP.h>
 210
 211 GP_Context *GP_ReadGIF(void *f, GP_ProgressCallback *callback);
 212 -------------------------------------------------------------------------------
 213
 214 Loads 'GIF' file into context. The pointer must point to the 'GIF' handle as
 215 returned by 'GP_OpenGIF()' function. The context, to store the image to, is
 216 allocated. The loading process could by aborted by a callback, in such case
 217 all memory is freed and the call returns 'NULL' and 'errno' is set to
 218 'ECANCELED'.
 219
 220 Currently this function loads only first image from the gif container.
 221
 222 [source,c]
 223 -------------------------------------------------------------------------------
 224 #include <loaders/GP_GIF.h>
 225 /* or */
 226 #include <GP.h>
 227
 228 GP_Context *GP_LoadGIF(const char *src_path, GP_ProgressCallback *callback);
 229 -------------------------------------------------------------------------------
 230
 231 Same as above but takes path to the file as a parameter and check for the
 232 signature. Basically this combines both of the calls above.
 233
 234 BMP
 235 ~~~
 236
 237 The 'BMP' loading support is nearly complete the only missing features should
 238 be fancy RGB compressions and RLE support.
 239
 240 [source,c]
 241 -------------------------------------------------------------------------------
 242 #include <loaders/GP_BMP.h>
 243 /* or */
 244 #include <GP.h>
 245
 246 int GP_OpenBMP(const char *src_path, FILE **f,
 247                GP_Size *w, GP_Size *h, GP_PixelType *pixel_type);
 248 -------------------------------------------------------------------------------
 249
 250 Opens file and checks for 'BMP' signature upon successful return (file could
 251 be opened, signature matches) zero is returned and the parameters, if
 252 non-'NULL', are initialized. Upon failure non-zero is returned and 'errno' is
 253 set.
 254
 255 This function is semi-internal, you should rather use functions listed below.
 256
 257 [source,c]
 258 -------------------------------------------------------------------------------
 259 #include <loaders/GP_BMP.h>
 260 /* or */
 261 #include <GP.h>
 262
 263 GP_Context *GP_ReadBMP(FILE *f, GP_ProgressCallback *callback);
 264 -------------------------------------------------------------------------------
 265
 266 Loads 'BMP' file into context. The 'FILE' pointer must point to opened 'BMP'
 267 file. The context, to store the image to, is allocated. The loading process
 268 could by aborted by a callback, in such case all memory is freed and the call
 269 returns 'NULL' and 'errno' is set to 'ECANCELED'.
 270
 271 Currently this function loads only first image from the 'GIF' container.
 272
 273 [source,c]
 274 -------------------------------------------------------------------------------
 275 #include <loaders/GP_BMP.h>
 276 /* or */
 277 #include <GP.h>
 278
 279 GP_Context *GP_LoadBMP(const char *src_path, GP_ProgressCallback *callback);
 280 -------------------------------------------------------------------------------
 281
 282 Same as above but takes path to the file as a parameter and check for the
 283 signature. Basically this combines both of the calls above.
 284
 285 PBM, PGM, PPM
 286 ~~~~~~~~~~~~~
 287
 288 There is a code do load and write 'PBM', 'PGM' and 'PPM' images too. However
 289 it's not finished and its API is outdated. Use at your own risk.
 290