src/lib/vampimg/ImagingTypes.pas

   1 {
   2   $Id: ImagingTypes.pas 171 2009-09-02 01:34:19Z galfar $
   3   Vampyre Imaging Library
   4   by Marek Mauder
   5   http://imaginglib.sourceforge.net
   6
   7   The contents of this file are used with permission, subject to the Mozilla
   8   Public License Version 1.1 (the "License"); you may not use this file except
   9   in compliance with the License. You may obtain a copy of the License at
  10   http://www.mozilla.org/MPL/MPL-1.1.html
  11
  12   Software distributed under the License is distributed on an "AS IS" basis,
  13   WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
  14   the specific language governing rights and limitations under the License.
  15
  16   Alternatively, the contents of this file may be used under the terms of the
  17   GNU Lesser General Public License (the  "LGPL License"), in which case the
  18   provisions of the LGPL License are applicable instead of those above.
  19   If you wish to allow use of your version of this file only under the terms
  20   of the LGPL License and not to allow others to use your version of this file
  21   under the MPL, indicate your decision by deleting  the provisions above and
  22   replace  them with the notice and other provisions required by the LGPL
  23   License.  If you do not delete the provisions above, a recipient may use
  24   your version of this file under either the MPL or the LGPL License.
  25
  26   For more information about the LGPL: http://www.gnu.org/copyleft/lesser.html
  27 }
  28
  29 { This unit contains basic types and constants used by Imaging library.}
  30 unit ImagingTypes;
  31
  32 {$I ImagingOptions.inc}
  33
  34 interface
  35
  36 const
  37   { Current Major version of Imaging.}
  38   ImagingVersionMajor = 0;
  39   { Current Minor version of Imaging.}
  40   ImagingVersionMinor = 26;
  41   { Current patch of Imaging.}
  42   ImagingVersionPatch = 4;
  43
  44   { Imaging Option Ids whose values can be set/get by SetOption/
  45     GetOption functions.}
  46
  47   { Defines Jpeg compression quality, ranges from 1 (ugly/small) to 100 (nice/large).
  48     Default value is 90.}
  49   ImagingJpegQuality           = 10;
  50   { Specifies whether Jpeg images are saved in progressive format,
  51     can be 0 or 1. Default value is 0.}
  52   ImagingJpegProgressive       = 11;
  53
  54   { Specifies whether Windows Bitmaps are saved using RLE compression
  55     (only for 1/4/8 bit images), can be 0 or 1. Default value is 1.}
  56   ImagingBitmapRLE             = 12;
  57
  58   { Specifies whether Targa images are saved using RLE compression,
  59     can be 0 or 1. Default value is 0.}
  60   ImagingTargaRLE              = 13;
  61
  62   { Value of this option is non-zero if last loaded DDS file was cube map.}
  63   ImagingDDSLoadedCubeMap      = 14;
  64   { Value of this option is non-zero if last loaded DDS file was volume texture.}
  65   ImagingDDSLoadedVolume       = 15;
  66   { Value of this option is number of mipmap levels of last loaded DDS image.}
  67   ImagingDDSLoadedMipMapCount  = 16;
  68   { Value of this option is depth (slices of volume texture or faces of
  69     cube map) of last loaded DDS image.}
  70   ImagingDDSLoadedDepth        = 17;
  71   { If it is non-zero next saved DDS file should be stored as cube map.}
  72   ImagingDDSSaveCubeMap        = 18;
  73   { If it is non-zero next saved DDS file should be stored as volume texture.}
  74   ImagingDDSSaveVolume         = 19;
  75   { Sets the number of mipmaps which should be stored in the next saved DDS file.
  76     Only applies to cube maps and volumes, ordinary 2D textures save all
  77     levels present in input.}
  78   ImagingDDSSaveMipMapCount    = 20;
  79   { Sets the depth (slices of volume texture or faces of cube map)
  80     of the next saved DDS file.}
  81   ImagingDDSSaveDepth          = 21;
  82
  83   { Sets precompression filter used when saving PNG images. Allowed values
  84     are: 0 (none), 1 (sub), 2 (up), 3 (average), 4 (paeth),
  85     5 (use 0 for indexed/gray images and 4 for RGB/ARGB images),
  86     6 (adaptive filtering - use best filter for each scanline - very slow).
  87     Note that filters 3 and 4 are much slower than filters 1 and 2.
  88     Default value is 5.}
  89   ImagingPNGPreFilter          = 25;
  90   { Sets ZLib compression level used when saving PNG images.
  91     Allowed values are in range 0 (no compresstion) to 9 (best compression).
  92     Default value is 5.}
  93   ImagingPNGCompressLevel      = 26;
  94   { Boolean option that specifies whether PNG images with more frames (APNG format)
  95     are animated by Imaging (according to frame disposal/blend methods) or just
  96     raw frames are loaded and sent to user (if you want to animate APNG yourself).
  97     Default value is 1.}
  98   ImagingPNGLoadAnimated       = 27;
  99
 100   { Specifies whether MNG animation frames are saved with lossy or lossless
 101     compression. Lossless frames are saved as PNG images and lossy frames are
 102     saved as JNG images. Allowed values are 0 (False) and 1 (True).
 103     Default value is 0.}
 104   ImagingMNGLossyCompression   = 28;
 105   { Defines whether alpha channel of lossy compressed MNG frames
 106     (when ImagingMNGLossyCompression is 1) is lossy compressed too.
 107     Allowed values are 0 (False) and 1 (True). Default value is 0.}
 108   ImagingMNGLossyAlpha         = 29;
 109   { Sets precompression filter used when saving MNG frames as PNG images.
 110     For details look at ImagingPNGPreFilter.}
 111   ImagingMNGPreFilter          = 30;
 112   { Sets ZLib compression level used when saving MNG frames as PNG images.
 113     For details look at ImagingPNGCompressLevel.}
 114   ImagingMNGCompressLevel      = 31;
 115   { Specifies compression quality used when saving MNG frames as JNG images.
 116     For details look at ImagingJpegQuality.}
 117   ImagingMNGQuality            = 32;
 118   { Specifies whether images are saved in progressive format when saving MNG
 119     frames as JNG images. For details look at ImagingJpegProgressive.}
 120   ImagingMNGProgressive        = 33;
 121
 122   { Specifies whether alpha channels of JNG images are lossy compressed.
 123     Allowed values are 0 (False) and 1 (True). Default value is 0.}
 124   ImagingJNGLossyAlpha         = 40;
 125   { Sets precompression filter used when saving lossless alpha channels.
 126     For details look at ImagingPNGPreFilter.}
 127   ImagingJNGAlphaPreFilter     = 41;
 128   { Sets ZLib compression level used when saving lossless alpha channels.
 129     For details look at ImagingPNGCompressLevel.}
 130   ImagingJNGAlphaCompressLevel = 42;
 131   { Defines compression quality used when saving JNG images (and lossy alpha channels).
 132     For details look at ImagingJpegQuality.}
 133   ImagingJNGQuality            = 43;
 134   { Specifies whether JNG images are saved in progressive format.
 135     For details look at ImagingJpegProgressive.}
 136   ImagingJNGProgressive        = 44;
 137   { Specifies whether PGM files are stored in text or in binary format.
 138     Allowed values are 0 (store as text - very! large files) and 1 (save binary).
 139     Default value is 1.}
 140   ImagingPGMSaveBinary         = 50;
 141   { Specifies whether PPM files are stored in text or in binary format.
 142     Allowed values are 0 (store as text - very! large files) and 1 (save binary).
 143     Default value is 1.}
 144   ImagingPPMSaveBinary         = 51;
 145   { Boolean option that specifies whether GIF images with more frames
 146     are animated by Imaging (according to frame disposal methods) or just
 147     raw frames are loaded and sent to user (if you want to animate GIF yourself).
 148     Default value is 1.
 149     Raw frames are 256 color indexed images (ifIndex8), whereas
 150     animated frames are always in 32bit ifA8R8G8B8 format (simplifies animating).}
 151   ImagingGIFLoadAnimated       = 56;
 152
 153   { This option is used when reducing number of colors used in
 154     image (mainly when converting from ARGB image to indexed
 155     format). Mask is 'anded' (bitwise AND) with every pixel's
 156     channel value when creating color histogram. If $FF is used
 157     all 8bits of color channels are used which can result in very
 158     slow proccessing of large images with many colors so you can
 159     use lower masks to speed it up (FC, F8 and F0 are good
 160     choices). Allowed values are in range <0, $FF> and default is
 161     $FE.                                                          }
 162   ImagingColorReductionMask   = 128;
 163   { This option can be used to override image data format during image
 164     loading. If set to format different from ifUnknown all loaded images
 165     are automaticaly converted to this format. Useful when you have
 166     many files in various formats but you want them all in one format for
 167     further proccessing. Allowed values are in
 168     range <Ord(Low(TImageFormat)), Ord(High(TImageFormat))> and
 169     default value is ifUnknown.}
 170   ImagingLoadOverrideFormat   = 129;
 171   { This option can be used to override image data format during image
 172     saving. If set to format different from ifUnknown all images
 173     to be saved are automaticaly internaly converted to this format.
 174     Note that image file formats support only a subset of Imaging data formats
 175     so final saved file may in different format than this override.
 176     Allowed values are in range <Ord(Low(TImageFormat)), Ord(High(TImageFormat))>
 177     and default value is ifUnknown.}
 178   ImagingSaveOverrideFormat   = 130;
 179   { Specifies resampling filter used when generating mipmaps. It is used
 180     in GenerateMipMaps low level function and Direct3D and OpenGL extensions.
 181     Allowed values are in range
 182     <Ord(Low(ImagingFormats.TSamplingFilter)), Ord(High(ImagingFormats.TSamplingFilter))>
 183     and default value is 1 (linear filter).}
 184   ImagingMipMapFilter         = 131;
 185
 186   { Returned by GetOption if given Option Id is invalid.}
 187   InvalidOption = -$7FFFFFFF;
 188
 189   { Indices that can be used to access channel values in array parts
 190     of structures like TColor32Rec. Note that this order can be
 191     used only for ARGB images. For ABGR image you must swap Red and Blue.}
 192   ChannelBlue  = 0;
 193   ChannelGreen = 1;
 194   ChannelRed   = 2;
 195   ChannelAlpha = 3;
 196
 197 type
 198   { Enum defining image data format. In formats with more channels,
 199     first channel after "if" is stored in the most significant bits and channel
 200     before end is stored in the least significant.}
 201   TImageFormat = (
 202     ifUnknown        = 0,
 203     ifDefault        = 1,
 204     { Indexed formats using palette.}
 205     ifIndex8         = 10,
 206     { Grayscale/Luminance formats.}
 207     ifGray8          = 40,
 208     ifA8Gray8        = 41,
 209     ifGray16         = 42,
 210     ifGray32         = 43,
 211     ifGray64         = 44,
 212     ifA16Gray16      = 45,
 213     { ARGB formats.}
 214     ifX5R1G1B1       = 80,
 215     ifR3G3B2         = 81,
 216     ifR5G6B5         = 82,
 217     ifA1R5G5B5       = 83,
 218     ifA4R4G4B4       = 84,
 219     ifX1R5G5B5       = 85,
 220     ifX4R4G4B4       = 86,
 221     ifR8G8B8         = 87,
 222     ifA8R8G8B8       = 88,
 223     ifX8R8G8B8       = 89,
 224     ifR16G16B16      = 90,
 225     ifA16R16G16B16   = 91,
 226     ifB16G16R16      = 92,
 227     ifA16B16G16R16   = 93,
 228     { Floating point formats.}
 229     ifR32F           = 170,
 230     ifA32R32G32B32F  = 171,
 231     ifA32B32G32R32F  = 172,
 232     ifR16F           = 173,
 233     ifA16R16G16B16F  = 174,
 234     ifA16B16G16R16F  = 175,
 235     { Special formats.}
 236     ifDXT1           = 220,
 237     ifDXT3           = 221,
 238     ifDXT5           = 222,
 239     ifBTC            = 223,
 240     ifATI1N          = 224,
 241     ifATI2N          = 225);
 242
 243   { Color value for 32 bit images.}
 244   TColor32 = LongWord;
 245   PColor32 = ^TColor32;
 246
 247   { Color value for 64 bit images.}
 248   TColor64 = type Int64;
 249   PColor64 = ^TColor64;
 250
 251   { Color record for 24 bit images, which allows access to individual color
 252     channels.}
 253   TColor24Rec = packed record
 254     case LongInt of
 255       0: (B, G, R: Byte);
 256       1: (Channels: array[0..2] of Byte);
 257   end;
 258   PColor24Rec = ^TColor24Rec;
 259   TColor24RecArray = array[0..MaxInt div SizeOf(TColor24Rec) - 1] of TColor24Rec;
 260   PColor24RecArray = ^TColor24RecArray;
 261
 262   { Color record for 32 bit images, which allows access to individual color
 263     channels.}
 264   TColor32Rec = packed record
 265     case LongInt of
 266       0: (Color: TColor32);
 267       1: (B, G, R, A: Byte);
 268       2: (Channels: array[0..3] of Byte);
 269       3: (Color24Rec: TColor24Rec);
 270   end;
 271   PColor32Rec = ^TColor32Rec;
 272   TColor32RecArray = array[0..MaxInt div SizeOf(TColor32Rec) - 1] of TColor32Rec;
 273   PColor32RecArray = ^TColor32RecArray;
 274
 275   { Color record for 48 bit images, which allows access to individual color
 276     channels.}
 277   TColor48Rec = packed record
 278     case LongInt of
 279       0: (B, G, R: Word);
 280       1: (Channels: array[0..2] of Word);
 281   end;
 282   PColor48Rec = ^TColor48Rec;
 283   TColor48RecArray = array[0..MaxInt div SizeOf(TColor48Rec) - 1] of TColor48Rec;
 284   PColor48RecArray = ^TColor48RecArray;
 285
 286   { Color record for 64 bit images, which allows access to individual color
 287     channels.}
 288   TColor64Rec = packed record
 289     case LongInt of
 290       0: (Color: TColor64);
 291       1: (B, G, R, A: Word);
 292       2: (Channels: array[0..3] of Word);
 293       3: (Color48Rec: TColor48Rec);
 294   end;
 295   PColor64Rec = ^TColor64Rec;
 296   TColor64RecArray = array[0..MaxInt div SizeOf(TColor64Rec) - 1] of TColor64Rec;
 297   PColor64RecArray = ^TColor64RecArray;
 298
 299   { Color record for 128 bit floating point images, which allows access to
 300     individual color channels.}
 301   TColorFPRec = packed record
 302     case LongInt of
 303       0: (B, G, R, A: Single);
 304       1: (Channels: array[0..3] of Single);
 305   end;
 306   PColorFPRec = ^TColorFPRec;
 307   TColorFPRecArray = array[0..MaxInt div SizeOf(TColorFPRec) - 1] of TColorFPRec;
 308   PColorFPRecArray = ^TColorFPRecArray;
 309
 310   { 16 bit floating-point value. It has 1 sign bit, 5 exponent bits,
 311     and 10 mantissa bits.}
 312   THalfFloat = type Word;
 313   PHalfFloat = ^THalfFloat;
 314
 315   { Color record for 64 bit floating point images, which allows access to
 316     individual color channels.}
 317   TColorHFRec = packed record
 318     case LongInt of
 319       0: (B, G, R, A: THalfFloat);
 320       1: (Channels: array[0..3] of THalfFloat);
 321   end;
 322   PColorHFRec = ^TColorHFRec;
 323   TColorHFRecArray = array[0..MaxInt div SizeOf(TColorHFRec) - 1] of TColorHFRec;
 324   PColorHFRecArray = ^TColorHFRecArray;
 325
 326   { Palette for indexed mode images with 32 bit colors.}
 327   TPalette32 = TColor32RecArray;
 328   TPalette32Size256 = array[0..255] of TColor32Rec;
 329   PPalette32 = ^TPalette32;
 330
 331   { Palette for indexd mode images with 24 bit colors.}
 332   TPalette24 = TColor24RecArray;
 333   TPalette24Size256 = array[0..255] of TColor24Rec;
 334   PPalette24 = ^TPalette24;
 335
 336   { Record that stores single image data and information describing it.}
 337   TImageData = packed record
 338     Width: LongInt;       // Width of image in pixels
 339     Height: LongInt;      // Height of image in pixels
 340     Format: TImageFormat; // Data format of image
 341     Size: LongInt;        // Size of image bits in Bytes
 342     Bits: Pointer;        // Pointer to memory containing image bits
 343     Palette: PPalette32;  // Image palette for indexed images
 344   end;
 345   PImageData = ^TImageData;
 346
 347   { Pixel format information used in conversions to/from 16 and 8 bit ARGB
 348     image formats.}
 349   TPixelFormatInfo = packed record
 350     ABitCount, RBitCount, GBitCount, BBitCount: Byte;
 351     ABitMask, RBitMask, GBitMask, BBitMask: LongWord;
 352     AShift, RShift, GShift, BShift: Byte;
 353     ARecDiv, RRecDiv, GRecDiv, BRecDiv: Byte;
 354   end;
 355   PPixelFormatInfo = ^TPixelFormatInfo;
 356
 357   PImageFormatInfo = ^TImageFormatInfo;
 358
 359   { Look at TImageFormatInfo.GetPixelsSize for details.}
 360   TFormatGetPixelsSizeFunc = function(Format: TImageFormat; Width,
 361     Height: LongInt): LongInt;
 362   { Look at TImageFormatInfo.CheckDimensions for details.}
 363   TFormatCheckDimensionsProc = procedure(Format: TImageFormat; var Width,
 364     Height: LongInt);
 365   { Function for getting pixel colors. Native pixel is read from Image and
 366     then translated to 32 bit ARGB.}
 367   TGetPixel32Func = function(Bits: Pointer; Info: PImageFormatInfo;
 368     Palette: PPalette32): TColor32Rec;
 369   { Function for getting pixel colors. Native pixel is read from Image and
 370     then translated to FP ARGB.}
 371   TGetPixelFPFunc = function(Bits: Pointer; Info: PImageFormatInfo;
 372     Palette: PPalette32): TColorFPRec;
 373   { Procedure for setting pixel colors. Input 32 bit ARGB color is translated to
 374     native format and then written to Image.}
 375   TSetPixel32Proc = procedure(Bits: Pointer; Info: PImageFormatInfo;
 376     Palette: PPalette32;const Color: TColor32Rec);
 377   { Procedure for setting pixel colors. Input FP ARGB color is translated to
 378     native format and then written to Image.}
 379   TSetPixelFPProc = procedure(Bits: Pointer; Info: PImageFormatInfo;
 380     Palette: PPalette32; const Color: TColorFPRec);
 381
 382   { Additional information for each TImageFormat value.}
 383   TImageFormatInfo = packed record
 384     Format: TImageFormat;             // Format described by this record
 385     Name: array[0..15] of Char;       // Symbolic name of format
 386     BytesPerPixel: LongInt;           // Number of bytes per pixel (note: it is
 387                                       // 0 for formats where BitsPerPixel < 8 (e.g. DXT).
 388                                       // Use GetPixelsSize function to get size of
 389                                       // image data.
 390     ChannelCount: LongInt;            // Number of image channels (R, G, B, A, Gray)
 391     PaletteEntries: LongInt;          // Number of palette entries
 392     HasGrayChannel: Boolean;          // True if image has grayscale channel
 393     HasAlphaChannel: Boolean;         // True if image has alpha channel
 394     IsFloatingPoint: Boolean;         // True if image has floating point pixels
 395     UsePixelFormat: Boolean;          // True if image uses pixel format
 396     IsRBSwapped: Boolean;             // True if Red and Blue channels are swapped
 397                                       // e.g. A16B16G16R16 has IsRBSwapped True
 398     RBSwapFormat: TImageFormat;       // Indicates supported format with swapped
 399                                       // Red and Blue channels, ifUnknown if such
 400                                       // format does not exist
 401     IsIndexed: Boolean;               // True if image uses palette
 402     IsSpecial: Boolean;               // True if image is in special format
 403     PixelFormat: PPixelFormatInfo;    // Pixel format structure
 404     GetPixelsSize: TFormatGetPixelsSizeFunc; // Returns size in bytes of
 405                                       // Width * Height pixels of image
 406     CheckDimensions: TFormatCheckDimensionsProc; // some formats have limited
 407                                       // values of Width and Height. This
 408                                       // procedure checks and changes dimensions
 409                                       // to be valid for given format.
 410     GetPixel32: TGetPixel32Func;      // 32bit ARGB pixel get function
 411     GetPixelFP: TGetPixelFPFunc;      // FP ARGB pixel get function
 412     SetPixel32: TSetPixel32Proc;      // 32bit ARGB pixel set procedure
 413     SetPixelFP: TSetPixelFPProc;      // FP ARGB pixel set procedure
 414     SpecialNearestFormat: TImageFormat; // Regular image format used when
 415                                       // compressing/decompressing special images
 416                                       // as source/target
 417   end;
 418
 419   { Handle to list of image data records.}
 420   TImageDataList = Pointer;
 421   PImageDataList = ^TImageDataList;
 422
 423   { Handle to input/output.}
 424   TImagingHandle = Pointer;
 425
 426   { Filters used in functions that resize images or their portions.}
 427   TResizeFilter = (
 428     rfNearest  = 0,
 429     rfBilinear = 1,
 430     rfBicubic  = 2);
 431
 432   { Seek origin mode for IO function Seek.}
 433   TSeekMode = (
 434    smFromBeginning = 0,
 435    smFromCurrent   = 1,
 436    smFromEnd       = 2);
 437
 438   { IO functions used for reading and writing images from/to input/output.}
 439   TOpenReadProc = function(Source: PChar): TImagingHandle; cdecl;
 440   TOpenWriteProc = function(Source: PChar): TImagingHandle; cdecl;
 441   TCloseProc = procedure(Handle: TImagingHandle); cdecl;
 442   TEofProc = function(Handle: TImagingHandle): Boolean; cdecl;
 443   TSeekProc = function(Handle: TImagingHandle; Offset: LongInt; Mode: TSeekMode): LongInt; cdecl;
 444   TTellProc = function(Handle: TImagingHandle): LongInt; cdecl;
 445   TReadProc = function(Handle: TImagingHandle; Buffer: Pointer; Count: LongInt): LongInt; cdecl;
 446   TWriteProc = function(Handle: TImagingHandle; Buffer: Pointer; Count: LongInt): LongInt; cdecl;
 447
 448 implementation
 449
 450 {
 451   File Notes:
 452
 453   -- TODOS ----------------------------------------------------
 454     - add lookup tables to pixel formats for fast conversions
 455
 456   -- 0.24.3 Changes/Bug Fixes ---------------------------------
 457     - Added ifATI1N and ifATI2N image data formats.
 458
 459   -- 0.23 Changes/Bug Fixes -----------------------------------
 460     - Added ifBTC image format and SpecialNearestFormat field
 461       to TImageFormatInfo.
 462
 463   -- 0.21 Changes/Bug Fixes -----------------------------------
 464     - Added option constants for PGM and PPM file formats.
 465     - Added TPalette32Size256 and TPalette24Size256 types.
 466
 467   -- 0.19 Changes/Bug Fixes -----------------------------------
 468     - added ImagingVersionPatch constant so bug fix only releases
 469       can be distinguished from ordinary major/minor releases
 470     - renamed TPixelFormat to TPixelFormatInfo to avoid name collisions
 471       with Graphics.TPixelFormat
 472     - added new image data formats:  ifR16F, ifA16R16G16B16F,
 473       ifA16B16G16R16F
 474     - added pixel get/set function pointers to TImageFormatInfo
 475     - added 16bit half float type and color record
 476     - renamed TColorFRec to TColorFPRec (and related types too)
 477
 478   -- 0.17 Changes/Bug Fixes -----------------------------------
 479     - added option ImagingMipMapFilter which now controls resampling filter
 480       used when generating mipmaps
 481     - added TResizeFilter type
 482     - added ChannelCount to TImageFormatInfo
 483     - added new option constants for MNG and JNG images
 484
 485   -- 0.15 Changes/Bug Fixes -----------------------------------
 486     - added RBSwapFormat to TImageFormatInfo for faster conversions
 487       between swapped formats (it just calls SwapChannels now if
 488       RBSwapFormat is not ifUnknown)
 489     - moved TImageFormatInfo and required types from Imaging unit
 490       here, removed TImageFormatShortInfo
 491     - added new options: ImagingLoadOverrideFormat, ImagingSaveOverrideFormat
 492
 493   -- 0.13 Changes/Bug Fixes -----------------------------------
 494     - new ImagingColorReductionMask option added
 495     - new image format added: ifA16Gray16
 496
 497 }
 498
 499 end.