doc/loaders.txt

   1 Pixmap loaders
   2 ---------------
   3 This part of GFXprim library implements API to load and save images for common
   4 image file formats.
   5
   6 Currently we support <<JPEG>>, <<PNG>>, <<BMP>>, <<TIFF>> and <<PNM>> images for
   7 loading and saving and <<GIF>>, <<JPEG2000>>, <<PCX>>, 'CBZ', <<PSD>> and
   8 <<PSP>> for loading.
   9
  10 Have a look at the link:about.html#Loaders[supported formats] for more
  11 detailed information.
  12
  13 Image Loaders and Savers
  14 ~~~~~~~~~~~~~~~~~~~~~~~~
  15
  16 Loading functions exists in at least two flavors. One that works with a path
  17 to a file and one that reads data from an link:loaders_io.html[IO stream].
  18
  19 All loading functions returns a pointer to newly allocated and loaded image or
  20 upon a failure NULL and errno is set.
  21
  22 The link:pixmap.html[Pixmap] returned by the loaders should be later freed
  23 with link:pixmap.html#PixmapFree[GP_PixmapFree()].
  24
  25 All saving functions returns zero on success and non-zero on failure. If image
  26 saving is aborted by a callback, the opened file is closed and removed from a
  27 file-system before the call returns.
  28
  29 The signature matching functions takes a 32 bytes long buffer and looks for a
  30 valid link:signatures.html[image signature]. If signature is found non-zero is
  31 returned.
  32
  33 .Possible errno values
  34 |===============================================================================
  35 | Any errno returned by underlying 'open()', 'close()', 'lseek()', 'read()',
  36   'write()', ...
  37 | 'ENOENT' if file doesn't exist
  38 | 'EACCES' if process doesn't have rights to open the file
  39 | 'ENOSYS' if GFXprim wasn't compiled with particular format support
  40 | 'ENOMEM' if returned by 'malloc()'
  41 | 'EIO', 'EINVAL' invalid image data (wrong signature, wrong or too short
  42   header or image data)
  43 | 'ECANCELED' action canceled by returning non-zero from within a
  44   link:progress_callback.html[callback].
  45 |===============================================================================
  46
  47 You can get more information about the error condition by turning on GFXprim
  48 link:environment_variables.html#GP_DEBUG[debug messages].
  49
  50 General interface
  51 ^^^^^^^^^^^^^^^^^
  52
  53 [[Load_Image]]
  54 [source,c]
  55 -------------------------------------------------------------------------------
  56 #include <loaders/GP_Loader.h>
  57 /* or */
  58 #include <GP.h>
  59
  60 GP_Pixmap *GP_LoadImage(const char *src_path, GP_ProgressCallback *callback);
  61 -------------------------------------------------------------------------------
  62
  63 Loads an image from a file.
  64
  65 The image format is first guessed by the file extension. If loader is found
  66 and if it succeeds to load the image the newly loaded image is returned.
  67
  68 If file extension based guess fails either because the extension wasn't
  69 matched or if the loader for the extension failed; the
  70 link:signatures.html[file signature] based method is used. The loader loads
  71 several bytes (currently 32) from the file and calls signature matching
  72 functions for each format that implements signature matching. If image
  73 signature is recognized, image loader it is called and the result is returned.
  74
  75 If file extension disagrees with file signature (which is quite common on the
  76 internet) a warning is printed into the stderr.
  77
  78 The resulting link:pixmap.html[Pixmap] should be later freed with
  79 link:pixmap.html#PixmapFree[GP_PixmapFree()].
  80
  81 [[Save_Image]]
  82 [source,c]
  83 -------------------------------------------------------------------------------
  84 #include <loaders/GP_Loader.h>
  85 /* or */
  86 #include <GP.h>
  87
  88 int GP_SaveImage(GP_Pixmap *src, const char *dst_path,
  89                  GP_ProgressCallback *callback);
  90 -------------------------------------------------------------------------------
  91
  92 Saves a link:pixmap.html[Pixmap] into a file.
  93
  94 The file format is matched accordingly to the file extension.
  95
  96 If extension is not found non-zero is returned and errno is set to 'EINVAL'.
  97
  98 If extension was found but support for saving the image format is not
  99 implemented errno is set to 'ENOSYS' (this may happen in case that GFXprim
 100 wasn't compiled with support for this image type).
 101
 102 If pixmap pixel type is not supported by the format errno is set to
 103 'EINVAL'.
 104
 105 [[Register_Loader]]
 106 Advanced Interface
 107 ^^^^^^^^^^^^^^^^^^
 108
 109 [source,c]
 110 -------------------------------------------------------------------------------
 111 typedef struct GP_Loader {
 112         /*
 113          * Reads an image from an IO stream.
 114          *
 115          * Returns newly allocated pixmap cotaining the loaded image or in
 116          * case of failure NULL and errno is set.
 117          */
 118         GP_Pixmap *(*Read)(GP_IO *io, GP_ProgressCallback *callback);
 119
 120         /*
 121          * Save an image.
 122          *
 123          * Returns zero on success, non-zero on failure and errno must be set.
 124          */
 125         int (*Save)(const GP_Pixmap *src, const char *dst_path,
 126                     GP_ProgressCallback *callback);
 127
 128         /*
 129          * GP_PIXEL_UNKNOWN terminated array of formats loader supports for save.
 130          *
 131          * This is _NOT_ a complete list loaders is able to save, due to automatic
 132          * conversions (i.e. RGB888 vs BRG888).
 133          */
 134         const GP_PixelType *save_ptypes;
 135
 136         /*
 137          * The buffer is filled with 32 bytes from an image start, returns 1 if
 138          * image signature was found zero otherwise.
 139          */
 140         int (*Match)(const void *buf);
 141
 142         /*
 143          * Short format name.
 144          */
 145         const char *fmt_name;
 146
 147         /*
 148          * NULL terminated array of file extensions.
 149          */
 150         const char *extensions[];
 151 } GP_Loader;
 152 -------------------------------------------------------------------------------
 153
 154 The 'GP_Loader' structure describes an image loader.
 155
 156 The 'Read', 'Save' and 'Match' functions could be NULL if the particular
 157 functionality is not implemented.
 158
 159 The 'fmt_name' is a short string that describes the format. For example:
 160 'Netbpm portable pixmap'.
 161
 162 The 'extensions' is NULL-terminated array of strings that holds all possible
 163 extensions that are commonly used for this image format.
 164
 165 [source,c]
 166 -------------------------------------------------------------------------------
 167 #include <loaders/GP_Loader.h>
 168 /* or */
 169 #include <GP.h>
 170
 171 void GP_ListLoaders(void);
 172
 173 int GP_LoaderRegister(const GP_Loader *self);
 174
 175 void GP_LoaderUnregister(const GP_Loader *self);
 176 -------------------------------------------------------------------------------
 177
 178 The 'GP_ListLoaders()' function prints all currently registered loaders and
 179 their capabilities into the stdout.
 180
 181 You can register and unregister your own loader by 'GP_LoaderRegister()' and
 182 'GP_LoaderUnregister()'. Once image loader is registered it's automatically
 183 used by all loaders functions.
 184
 185 The 'GP_LoaderRegister()' can fail (return non-zero) if you try to register
 186 loader that is allready registered or if the loaders table is full (the table
 187 size is compile time constant and there should be space for at least fifty
 188 user defined loaders). I this cases the errno would be set to 'EEXIST' or
 189 'ENOSPC' respectively.
 190
 191 TIP: For example usage see image loader registration
 192 link:example_loader_registration.html[example].
 193
 194 [source,c]
 195 -------------------------------------------------------------------------------
 196 #include <loaders/GP_Loader.h>
 197 /* or */
 198 #include <GP.h>
 199
 200 const GP_Loader *GP_LoaderBySignature(const void *buf)
 201 -------------------------------------------------------------------------------
 202
 203 Returns pointer to image loader accordingly to image signature or NULL if no
 204 suitable loader was found. The buf pointer must point to a buffer at least 32
 205 bytes long.
 206
 207 [source,c]
 208 -------------------------------------------------------------------------------
 209 #include <loaders/GP_Loader.h>
 210 /* or */
 211 #include <GP.h>
 212
 213 const GP_Loader *GP_LoaderByFilename(const char *path)
 214 -------------------------------------------------------------------------------
 215
 216 Matches loader by the file extension. This function does not check that the
 217 file exists or that it could be opened etc. It only looks at the file
 218 extension (i.e. string at the end of the path after a dot) and matches it
 219 against extensions defined by loaders.
 220
 221 [source,c]
 222 -------------------------------------------------------------------------------
 223 #include <loaders/GP_Loader.h>
 224 /* or */
 225 #include <GP.h>
 226
 227 GP_Pixmap *GP_LoaderLoadImage(const GP_Loader *self, const char *src_path,
 228                                GP_ProgressCallback *callback);
 229 -------------------------------------------------------------------------------
 230
 231 Loads an image given a loader structure.
 232
 233 Returns NULL and sets errno to 'ENOSYS' loader 'Read()' callback is NULL.
 234
 235 Otherwise prepares a link:loaders_io.html[GP_IO] from the 'src_path' file,
 236 calls the 'Read()' callbacks and closes the 'IO' before the call returns.
 237
 238 [[PNG]]
 239 PNG Loader
 240 ~~~~~~~~~~
 241 The 'PNG' image support is implemented by the
 242 link:http://www.libpng.org/[libpng library].
 243
 244 [source,c]
 245 -------------------------------------------------------------------------------
 246 #include <loaders/GP_PNG.h>
 247 /* or */
 248 #include <GP.h>
 249
 250 GP_Pixmap *GP_ReadPNG(GP_IO *io, GP_ProgressCallback *callback);
 251 -------------------------------------------------------------------------------
 252
 253 Reads a 'PNG' image from readable 'GP_IO'. The link:loaders_io.html[IO stream]
 254 is expected to start exactly at the 'PNG' file signature.
 255
 256 Returns newly allocated pixmap (containing decompressed image) or in case of
 257 failure NULL and errno is set.
 258
 259 The resulting link:pixmap.html[Pixmap] should be later freed with
 260 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 261
 262 [source,c]
 263 -------------------------------------------------------------------------------
 264 #include <loaders/GP_PNG.h>
 265 /* or */
 266 #include <GP.h>
 267
 268 GP_Pixmap *GP_LoadPNG(const char *src_path, GP_ProgressCallback *callback);
 269 -------------------------------------------------------------------------------
 270
 271 Loads a 'PNG' image from a file.
 272
 273 Returns a pointer to newly allocated loaded image, or in case of failure
 274 NULL and errno is set.
 275
 276 The resulting link:pixmap.html[Pixmap] should be later freed with
 277 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 278
 279 [source,c]
 280 -------------------------------------------------------------------------------
 281 #include <loaders/GP_PNG.h>
 282 /* or */
 283 #include <GP.h>
 284
 285 int GP_SavePNG(const GP_Pixmap *src, const char *dst_path,
 286                GP_ProgressCallback *callback);
 287 -------------------------------------------------------------------------------
 288
 289 Saves a link:pixmap.html[Pixmap] as a 'PNG' image, in case particular pixel
 290 type is not supported non-zero is returned and errno is set to 'ENOSYS'.
 291
 292 Supports 'G1', 'G2', 'G4', 'G8', 'G16', and 8-bit 'RGB' and 'RGBA' pixel
 293 types.
 294
 295 [source,c]
 296 -------------------------------------------------------------------------------
 297 #include <loaders/GP_PNG.h>
 298 /* or */
 299 #include <GP.h>
 300
 301 int GP_MatchPNG(const void *buf);
 302 -------------------------------------------------------------------------------
 303
 304 Matches a 'PNG' link:signatures.html[file signature]. Returns non-zero if found.
 305
 306 [[JPEG]]
 307 JPEG Loader
 308 ~~~~~~~~~~~
 309 The 'JPEG' image support is implemented by the jpeg library.
 310
 311 [source,c]
 312 -------------------------------------------------------------------------------
 313 #include <loaders/GP_JPG.h>
 314 /* or */
 315 #include <GP.h>
 316
 317 GP_Pixmap *GP_ReadJPG(GP_IO *io, GP_ProgressCallback *callback);
 318 -------------------------------------------------------------------------------
 319
 320 Reads a 'JPEG' image from readable 'GP_IO'. The link:loaders_io.html[IO
 321 stream] is expected to start exactly at the 'JPEG' file signature.
 322
 323 Returns newly allocated pixmap (containing decompressed image) or in case of
 324 failure NULL and errno is set.
 325
 326 The resulting link:pixmap.html[Pixmap] should be later freed with
 327 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 328
 329 [source,c]
 330 -------------------------------------------------------------------------------
 331 #include <loaders/GP_JPG.h>
 332 /* or */
 333 #include <GP.h>
 334
 335 GP_Pixmap *GP_LoadJPG(const char *src_path, GP_ProgressCallback *callback);
 336 -------------------------------------------------------------------------------
 337
 338 Loads a 'JPEG' image from a file.
 339
 340 Returns a pointer to newly allocated loaded image, or in case of failure
 341 NULL and errno is set.
 342
 343 The resulting link:pixmap.html[Pixmap] should be later freed with
 344 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 345
 346 [source,c]
 347 -------------------------------------------------------------------------------
 348 #include <loaders/GP_JPG.h>
 349 /* or */
 350 #include <GP.h>
 351
 352 int GP_SaveJPG(const GP_Pixmap *src, const char *dst_path,
 353                GP_ProgressCallback *callback);
 354 -------------------------------------------------------------------------------
 355
 356 Saves a link:pixmap.html[Pixmap] as a 'JPEG' image.
 357
 358 The 'JPEG' format could store either 'G8' or 8-bit 'RGB' pixel-types.
 359
 360 [source,c]
 361 -------------------------------------------------------------------------------
 362 #include <loaders/GP_JPG.h>
 363 /* or */
 364 #include <GP.h>
 365
 366 int GP_MatchJPG(const void *buf);
 367 -------------------------------------------------------------------------------
 368
 369 Matches a 'JPEG' link:signatures.html[file signature]. Returns non-zero if
 370 found.
 371
 372 [[JPEG2000]]
 373 JPEG 2000 Loader
 374 ~~~~~~~~~~~~~~~~
 375 The 'JPEG 2000' image support is implemented using the openjpeg library.
 376
 377 [source,c]
 378 -------------------------------------------------------------------------------
 379 #include <loaders/GP_JP2.h>
 380 /* or */
 381 #include <GP.h>
 382
 383 GP_Pixmap *GP_ReadJP2(GP_IO *io, GP_ProgressCallback *callback);
 384 -------------------------------------------------------------------------------
 385
 386 Reads a 'JPEG2000' image from readable 'GP_IO'. The link:loaders_io.html[IO
 387 stream] is expected to start exactly at the 'JPEG2000' file signature.
 388
 389 Returns newly allocated pixmap (containing decompressed image) or in case of
 390 failure NULL and errno is set.
 391
 392 The resulting link:pixmap.html[Pixmap] should be later freed with
 393 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 394
 395 NOTE: Due to limitations of the openjpeg library progress callback does not work.
 396
 397 [source,c]
 398 -------------------------------------------------------------------------------
 399 #include <loaders/GP_JP2.h>
 400 /* or */
 401 #include <GP.h>
 402
 403 GP_Pixmap *GP_LoadJP2(const char *src_path, GP_ProgressCallback *callback);
 404 -------------------------------------------------------------------------------
 405
 406 Loads a 'JPEG2000' image from a file.
 407
 408 The resulting link:pixmap.html[Pixmap] should be later freed with
 409 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 410
 411 NOTE: Due to limitations of the openjpeg library progress callback does not work.
 412
 413 [source,c]
 414 -------------------------------------------------------------------------------
 415 #include <loaders/GP_JP2.h>
 416 /* or */
 417 #include <GP.h>
 418
 419 int GP_MatchJP2(const void *buf);
 420 -------------------------------------------------------------------------------
 421
 422 Matches a 'JPEG2000' link:signatures.html[file signature]. Returns non-zero if
 423 found.
 424
 425 [[GIF]]
 426 GIF Loader
 427 ~~~~~~~~~~
 428
 429 The 'GIF' image support is implemented using the
 430 link:http://sourceforge.net/projects/giflib/[giflib library].
 431
 432 [source,c]
 433 -------------------------------------------------------------------------------
 434 #include <loaders/GP_GIF.h>
 435 /* or */
 436 #include <GP.h>
 437
 438 GP_Pixmap *GP_ReadGIF(GP_IO *io, GP_ProgressCallback *callback);
 439 -------------------------------------------------------------------------------
 440
 441 Reads a 'GIF' image from readable 'GP_IO'. The link:loaders_io.html[IO stream]
 442 is expected to start exactly at the 'GIF' file signature.
 443
 444 Returns newly allocated pixmap (containing decompressed image) or in case of
 445 failure NULL and errno is set.
 446
 447 The resulting link:pixmap.html[Pixmap] should be later freed with
 448 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 449
 450 NOTE: Currently this function loads only first image from the 'GIF' container.
 451
 452 [source,c]
 453 -------------------------------------------------------------------------------
 454 #include <loaders/GP_GIF.h>
 455 /* or */
 456 #include <GP.h>
 457
 458 GP_Pixmap *GP_LoadGIF(const char *src_path, GP_ProgressCallback *callback);
 459 -------------------------------------------------------------------------------
 460
 461 Loads a 'GIF' image from a file.
 462
 463 The resulting link:pixmap.html[Pixmap] should be later freed with
 464 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 465
 466 [source,c]
 467 -------------------------------------------------------------------------------
 468 #include <loaders/GP_GIF.h>
 469 /* or */
 470 #include <GP.h>
 471
 472 int GP_MatchGIF(const void *buf);
 473 -------------------------------------------------------------------------------
 474
 475 Matches a 'GIF' link:signatures.html[file signature]. Returns non-zero if
 476 found.
 477
 478 [[BMP]]
 479 BMP Loader
 480 ~~~~~~~~~~
 481
 482 The 'BMP' loading support is nearly complete the only missing features should
 483 be exotic RGB compressions (RGB101010 for example) and RLE4 support.
 484
 485 [source,c]
 486 -------------------------------------------------------------------------------
 487 #include <loaders/GP_BMP.h>
 488 /* or */
 489 #include <GP.h>
 490
 491 GP_Pixmap *GP_ReadBMP(GP_IO *io, GP_ProgressCallback *callback);
 492 -------------------------------------------------------------------------------
 493
 494 Reads a 'BMP' image from readable 'GP_IO'. The link:loaders_io.html[IO stream]
 495 is expected to start exactly at the 'BMP' file signature.
 496
 497 Returns newly allocated pixmap (containing decompressed image) or in case of
 498 failure NULL and errno is set.
 499
 500 The resulting link:pixmap.html[Pixmap] should be later freed with
 501 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 502
 503 [source,c]
 504 -------------------------------------------------------------------------------
 505 #include <loaders/GP_BMP.h>
 506 /* or */
 507 #include <GP.h>
 508
 509 GP_Pixmap *GP_LoadBMP(const char *src_path, GP_ProgressCallback *callback);
 510 -------------------------------------------------------------------------------
 511
 512 Loads a 'BMP' image from a file.
 513
 514 The resulting link:pixmap.html[Pixmap] should be later freed with
 515 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 516
 517 [source,c]
 518 -------------------------------------------------------------------------------
 519 #include <loaders/GP_BMP.h>
 520 /* or */
 521 #include <GP.h>
 522
 523 int GP_SaveBMP(const GP_Pixmap *src, const char *dst_path,
 524                GP_ProgressCallback *callback);
 525 -------------------------------------------------------------------------------
 526
 527 Saves a link:pixmap.html[Pixmap] as a 'BMP' image.
 528
 529 Currently only 8-bit 'RGB' pixel types are supported.
 530
 531 [source,c]
 532 -------------------------------------------------------------------------------
 533 #include <loaders/GP_BMP.h>
 534 /* or */
 535 #include <GP.h>
 536
 537 int GP_MatchBMP(const void *buf);
 538 -------------------------------------------------------------------------------
 539
 540 Matches a 'BMP' link:signatures.html[file signature]. Returns non-zero if
 541 found.
 542
 543 [[TIFF]]
 544 TIFF Loader
 545 ~~~~~~~~~~~
 546
 547 The 'TIFF' loader support is done using the
 548 link:http://www.remotesensing.org/libtiff/[tiff library].
 549
 550 Currently only subset of 'tiff' images could be loaded, tiles does not work
 551 yet.
 552
 553 [source,c]
 554 -------------------------------------------------------------------------------
 555 #include <loaders/GP_TIFF.h>
 556 /* or */
 557 #include <GP.h>
 558
 559 GP_Pixmap *GP_ReadTIFF(GP_IO *io, GP_ProgressCallback *callback);
 560 -------------------------------------------------------------------------------
 561
 562 Reads a 'TIFF' image from readable 'GP_IO'. The link:loaders_io.html[IO stream]
 563 is expected to start exactly at the 'TIFF' file signature.
 564
 565 Returns newly allocated pixmap (containing decompressed image) or in case of
 566 failure NULL and errno is set.
 567
 568 The resulting link:pixmap.html[Pixmap] should be later freed with
 569 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 570
 571 [source,c]
 572 -------------------------------------------------------------------------------
 573 #include <loaders/GP_TIFF.h>
 574 /* or */
 575 #include <GP.h>
 576
 577 GP_Pixmap *GP_LoadTIFF(const char *src_path, GP_ProgressCallback *callback);
 578 -------------------------------------------------------------------------------
 579
 580 Loads a 'TIFF' image from a file.
 581
 582 The resulting link:pixmap.html[Pixmap] should be later freed with
 583 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 584
 585 [source,c]
 586 -------------------------------------------------------------------------------
 587 #include <loaders/GP_TIFF.h>
 588 /* or */
 589 #include <GP.h>
 590
 591 int GP_SaveTIFF(const GP_Pixmap *src, const char *dst_path,
 592                 GP_ProgressCallback *callback);
 593 -------------------------------------------------------------------------------
 594
 595 Saves a link:pixmap.html[Pixmap] as a 'TIFF' image.
 596
 597 Supports 'G1', 'G2', 'G4' and 'G8' grayscale and 8-bit 'RGB' pixel types.
 598
 599 The image is saved in stripes.
 600
 601 [source,c]
 602 -------------------------------------------------------------------------------
 603 #include <loaders/GP_TIFF.h>
 604 /* or */
 605 #include <GP.h>
 606
 607 int GP_MatchTIFF(const void *buf);
 608 -------------------------------------------------------------------------------
 609
 610 Matches a 'TIFF' link:signatures.html[file signature]. Returns non-zero if
 611 found.
 612
 613 [[PSP]]
 614 PSP Loader
 615 ~~~~~~~~~~
 616
 617 The 'PSP' loader can load a composite image from a Paint Shop Pro Image Files.
 618
 619 [source,c]
 620 -------------------------------------------------------------------------------
 621 #include <loaders/GP_PSP.h>
 622 /* or */
 623 #include <GP.h>
 624
 625 GP_Pixmap *GP_ReadPSP(GP_IO *io, GP_ProgressCallback *callback);
 626 -------------------------------------------------------------------------------
 627
 628 Reads a 'PSP' composite image from readable 'GP_IO'. The
 629 link:loaders_io.html[IO stream] is expected to start exactly at the 'PSP' file
 630 signature.
 631
 632 Returns newly allocated pixmap (containing decompressed image) or in case of
 633 failure NULL and errno is set.
 634
 635 The resulting link:pixmap.html[Pixmap] should be later freed with
 636 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 637
 638 [source,c]
 639 -------------------------------------------------------------------------------
 640 #include <loaders/GP_PSP.h>
 641 /* or */
 642 #include <GP.h>
 643
 644 GP_Pixmap *GP_LoadPSP(const char *src_path, GP_ProgressCallback *callback);
 645 -------------------------------------------------------------------------------
 646
 647 Loads a composite image from a 'PSP' file.
 648
 649 The resulting link:pixmap.html[Pixmap] should be later freed with
 650 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 651
 652 [source,c]
 653 -------------------------------------------------------------------------------
 654 #include <loaders/GP_PSP.h>
 655 /* or */
 656 #include <GP.h>
 657
 658 int GP_MatchPSP(const void *buf);
 659 -------------------------------------------------------------------------------
 660
 661 Matches a 'PSP' link:signatures.html[file signature]. Returns non-zero if
 662 found.
 663
 664 [[PSD]]
 665 PSD Loader
 666 ~~~~~~~~~~
 667
 668 The 'PSD' loader can load a merged image (if present) or a thumbnail from an
 669 Adobe Photoshop Image. Currently 16bit RGB and 16bit CMYK is not supported and
 670 the loader will fallback to the thumbnail in this case (which is always 8bit
 671 RGB).
 672
 673 [source,c]
 674 -------------------------------------------------------------------------------
 675 #include <loaders/GP_PSD.h>
 676 /* or */
 677 #include <GP.h>
 678
 679 GP_Pixmap *GP_ReadPSD(GP_IO *io, GP_ProgressCallback *callback);
 680 -------------------------------------------------------------------------------
 681
 682 Reads a 'PSD' image from readable 'GP_IO'. The link:loaders_io.html[IO stream]
 683 is expected to start exactly at the 'PSD' file signature.
 684
 685 Returns newly allocated pixmap (containing decompressed image) or in case of
 686 failure NULL and errno is set.
 687
 688 The resulting link:pixmap.html[Pixmap] should be later freed with
 689 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 690
 691 [source,c]
 692 -------------------------------------------------------------------------------
 693 #include <loaders/GP_PSD.h>
 694 /* or */
 695 #include <GP.h>
 696
 697 GP_Pixmap *GP_LoadPSD(const char *src_path, GP_ProgressCallback *callback);
 698 -------------------------------------------------------------------------------
 699
 700 Loads a merged image (if present) from a 'PSD' file.
 701
 702 Fallbacks to thumbnail if merged image is not present or has unsupported pixel
 703 type.
 704
 705 Returns NULL (TODO ERRNO) if merged image is not present/supported and
 706 thumbnail is not present either.
 707
 708 The resulting link:pixmap.html[Pixmap] should be later freed with
 709 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 710
 711 [source,c]
 712 -------------------------------------------------------------------------------
 713 #include <loaders/GP_PSD.h>
 714 /* or */
 715 #include <GP.h>
 716
 717 int GP_MatchPSD(const void *buf);
 718 -------------------------------------------------------------------------------
 719
 720 Matches a 'PSD' link:signatures.html[file signature]. Returns non-zero if
 721 found.
 722
 723 [[PNM]]
 724 PNM Loaders
 725 ~~~~~~~~~~~
 726
 727 [source,c]
 728 -------------------------------------------------------------------------------
 729 #include <loaders/GP_PNM.h>
 730 /* or */
 731 #include <GP.h>
 732
 733 GP_Pixmap *GP_ReadPBM(GP_IO *io, GP_ProgressCallback *callback);
 734
 735 GP_Pixmap *GP_ReadPGM(GP_IO *io, GP_ProgressCallback *callback);
 736
 737 GP_Pixmap *GP_ReadPPM(GP_IO *io, GP_ProgressCallback *callback);
 738
 739 GP_Pixmap *GP_ReadPNM(GP_IO *io, GP_ProgressCallback *callback);
 740 -------------------------------------------------------------------------------
 741
 742 Reads a ASCII or Rawbits (binary) 'PBM', 'PGM' and 'PPM' image from readable
 743 'GP_IO'. The link:loaders_io.html[IO stream] is expected to start exactly at
 744 the file signature.
 745
 746 The resulting link:pixmap.html[Pixmap] should be later freed with
 747 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 748
 749 [source,c]
 750 -------------------------------------------------------------------------------
 751 #include <loaders/GP_PNM.h>
 752 /* or */
 753 #include <GP.h>
 754
 755 GP_Pixmap *GP_LoadPBM(const char *src_path, GP_ProgressCallback *callback);
 756
 757 GP_Pixmap *GP_LoadPGM(const char *src_path, GP_ProgressCallback *callback);
 758
 759 GP_Pixmap *GP_LoadPPM(const char *src_path, GP_ProgressCallback *callback);
 760
 761 GP_Pixmap *GP_LoadPNM(const char *src_path, GP_ProgressCallback *callback);
 762 -------------------------------------------------------------------------------
 763
 764 Loads either ASCII or Rawbits (binary) 'PBM', 'PGM' and 'PPM'.
 765
 766 The 'PNM' loader can load all of them i.e. 'PBM', 'PGM' and 'PPM'.
 767
 768 The resulting link:pixmap.html[Pixmap] should be later freed with
 769 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 770
 771 [source,c]
 772 -------------------------------------------------------------------------------
 773 #include <loaders/GP_PNM.h>
 774 /* or */
 775 #include <GP.h>
 776
 777 GP_Pixmap *GP_SavePBM(const GP_Pixmap *src, const char *dst_path,
 778                        GP_ProgressCallback *callback);
 779 -------------------------------------------------------------------------------
 780
 781 Saves 'G1' (1 bit grayscale) image as ASCII 'PBM'.
 782
 783 [source,c]
 784 -------------------------------------------------------------------------------
 785 #include <loaders/GP_PNM.h>
 786 /* or */
 787 #include <GP.h>
 788
 789 GP_Pixmap *GP_SavePGM(const GP_Pixmap *src, const char *dst_path,
 790                        GP_ProgressCallback *callback);
 791 -------------------------------------------------------------------------------
 792
 793 Saves 'G1', 'G2', 'G4' and 'G8' (1, 2, 4 and 8 bit grayscale) image as ASCII
 794 'PGM'.
 795
 796 [source,c]
 797 -------------------------------------------------------------------------------
 798 #include <loaders/GP_PNM.h>
 799 /* or */
 800 #include <GP.h>
 801
 802 GP_Pixmap *GP_SavePPM(const GP_Pixmap *src, const char *dst_path,
 803                        GP_ProgressCallback *callback);
 804 -------------------------------------------------------------------------------
 805
 806 Saves 'RGB888' (24 bit RGB) image as ASCII 'PPM'.
 807
 808 [source,c]
 809 -------------------------------------------------------------------------------
 810 #include <loaders/GP_PNM.h>
 811 /* or */
 812 #include <GP.h>
 813
 814 GP_Pixmap *GP_SavePNM(const GP_Pixmap *src, const char *dst_path,
 815                        GP_ProgressCallback *callback);
 816 -------------------------------------------------------------------------------
 817
 818 Saves 'G1', 'G2', 'G4' and 'G8' (1, 2, 4, 8 bit grayscale) or 'RGB888' (24 bit
 819 RGB) image as ASCII 'PNM'.
 820
 821 [source,c]
 822 -------------------------------------------------------------------------------
 823 #include <loaders/GP_PNM.h>
 824 /* or */
 825 #include <GP.h>
 826
 827 int GP_MatchPBM(const void *buf);
 828
 829 int GP_MatchPGM(const void *buf);
 830
 831 int GP_MatchPPM(const void *buf);
 832
 833 int GP_MatchPNM(const void *buf);
 834 -------------------------------------------------------------------------------
 835
 836 Matches either ASCII or Rawbits (binary) 'PBM', 'PGM' and 'PPM'
 837 link:signatures.html[file signatures].
 838
 839 The 'PNM' matches all of the formats. i.e. 'PBM', 'PGM' and 'PPM'.
 840
 841 All functions return non-zero if found.
 842
 843 [[PCX]]
 844 PCX Loader
 845 ~~~~~~~~~~
 846
 847 The 'PCX' loader can load ZSoft PCX images.
 848
 849 [source,c]
 850 -------------------------------------------------------------------------------
 851 #include <loaders/GP_PCX.h>
 852 /* or */
 853 #include <GP.h>
 854
 855 GP_Pixmap *GP_ReadPCX(GP_IO *io, GP_ProgressCallback *callback);
 856 -------------------------------------------------------------------------------
 857
 858 Reads a 'PCX' image from readable 'GP_IO'. The link:loaders_io.html[IO stream]
 859 is expected to start exactly at the 'PCX' file signature.
 860
 861 Returns newly allocated pixmap (containing decompressed image) or in case of
 862 failure NULL and errno is set.
 863
 864 The resulting link:pixmap.html[Pixmap] should be later freed with
 865 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 866
 867 [source,c]
 868 -------------------------------------------------------------------------------
 869 #include <loaders/GP_PCX.h>
 870 /* or */
 871 #include <GP.h>
 872
 873 GP_Pixmap *GP_LoadPCX(const char *src_path, GP_ProgressCallback *callback);
 874 -------------------------------------------------------------------------------
 875
 876 Loads a 'PCX' image from a file.
 877
 878 The resulting link:pixmap.html[Pixmap] should be later freed with
 879 link:pixmap.html#PixmapFree[GP_PixmapFree()].
 880
 881 [source,c]
 882 -------------------------------------------------------------------------------
 883 #include <loaders/GP_PCX.h>
 884 /* or */
 885 #include <GP.h>
 886
 887 int GP_MatchPCX(const void *buf);
 888 -------------------------------------------------------------------------------
 889
 890 Matches a 'PCX' link:signatures.html[file signature]. Returns non-zero if
 891 found.