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