Differences between revisions 6 and 7

Image Files with Dyalog

As presented in Vector 23:1 here's a Dyalog workspace that offers easy access to an image toolbox. It hooks into the open source image library OpenIL and exposes some of the functionality offered.

In order to use the code in the workspace you will also need to download OpenIL itself, which comes in the shape of 3 DLLs.

The code as presented here is in an immediately deployable state. It does however not cover all that OpenIL has to offer but more "flowers from the OpenIL bouquet" can easily be added and I expect to do so irregularly.

The workspace contains only one namespace, which holds all code required. To get started have a look at the variable 'readme' in that namespace.

Zipped Dyalog v9 workspace: OpenIL.zip

OpenIL downloads: OpenIL

Opening the Developer's Image Library

Encouraged by Vector's editor I here present the code in the Dyalog v9 workspace that went with the original article in Vector.

Interface code

Originally inspired by an article by Morten Kromberg I structured the interface to OpenIL to an OO object look-alike. The following functions (until the next headline) all come from the namespace, which in my workspace is called 'DevIL'. The first function listed, the "constructor" New, creates another namespace that holds all the name associations and other "methods" that the object offers.

 REF←New;dummy
⍝ Creates new DevIL-object (basically a link to an instance of DevIL)
⍝ Returns a reference to a namespace
 REF←⎕NS'Load' 'Resize' 'GetFormat' 'GetType' 'GetSize' 'GetBits' 'GetCMap' 'GetCBits' 'DecodeRGB' 'EncodeRGB' 'Set' 'Save' 'ErrorHandler'

 REF.⎕NA'DevIL|ilInit'  ⍝ DLL with basic functionality
 REF.⎕NA'ILU|iluInit'   ⍝ DLL with additional stuff, e.g. resizing

⍝ ILvoid ilGenImages(ILsizei Num, ILuint *Images);
⍝ Use ilGenImages to generate image "names"
 REF.⎕NA'DevIL|ilGenImages I4 >U4[]'
⍝ ILvoid ilBindImage(ILuint Image);
⍝ ilBindImage binds the current image to the image described by the image "name" in Image.
 REF.⎕NA'DevIL|ilBindImage U4'
⍝ ILvoid ilDeleteImages(ILsizei Num, ILuint *Images);
⍝ ilDeleteImages deletes image "names"
 REF.⎕NA'DevIL|ilDeleteImages I4 <U4[]'

⍝ ILboolean ilLoadImage(const char *FileName);
 REF.⎕NA'I DevIL|ilLoadImage <0T[]'
⍝ ILboolean ilLoad(ILenum Type, const char *FileName);
⍝ If IL_TYPE_UNKNOWN is specified for Type, ilLoad behaves exactly like ilLoadImage.
 REF.⎕NA'I DevIL|ilLoad U4 <0T[]'

⍝ ILboolean ilSaveImage(const char *FileName);
 REF.⎕NA'I DevIL|ilSaveImage <0T[]'
⍝ ILboolean ilSave(ILenum Type, const char *FileName);
 REF.⎕NA'I DevIL|ilSave U4 <0T[]'

⍝ ILuint ilCopyPixels(
⍝  ILuint XOff, ILuint YOff, ILuint ZOff,
⍝  ILuint Width, ILuint Height, ILuint Depth,
⍝  ILenum Format, ILenum Type, ILvoid *Data);
 REF.⎕NA'I DevIL|ilCopyPixels U U U U U U U4 U4 >U1[]'

⍝ ILboolean ilTexImage(ILuint Width, ILuint Height, ILuint Depth,
⍝                      ILubyte Bpp, ILenum Format, ILenum Type, ILvoid *Data);
 REF.⎕NA'I DevIL|ilTexImage U4 U4 U4 U1 U4 U4 <U1[]'

⍝ ILuintY ilGetInteger(ILenum Mode);
 REF.⎕NA'I DevIL|ilGetInteger U4'
⍝ ILvoid  ilSetInteger(ILenum Mode, ILint Param);
 REF.⎕NA'DevIL|ilSetInteger U4 U4'

⍝ File format-specific constants
⍝#define IL_TGA_CREATE_STAMP        0x0710
⍝#define IL_JPG_QUALITY             0x0711 = 1809
⍝#define IL_PNG_INTERLACE           0x0712
⍝#define IL_TGA_RLE                 0x0713
⍝#define IL_BMP_RLE                 0x0714
⍝#define IL_SGI_RLE                 0x0715
⍝#define IL_TGA_ID_STRING           0x0717
⍝#define IL_TGA_AUTHNAME_STRING     0x0718
⍝#define IL_TGA_AUTHCOMMENT_STRING  0x0719
⍝#define IL_PNG_AUTHNAME_STRING     0x071A
⍝#define IL_PNG_TITLE_STRING        0x071B
⍝#define IL_PNG_DESCRIPTION_STRING  0x071C
⍝#define IL_TIF_DESCRIPTION_STRING  0x071D
⍝#define IL_TIF_HOSTCOMPUTER_STRING 0x071E
⍝#define IL_TIF_DOCUMENTNAME_STRING 0x071F
⍝#define IL_TIF_AUTHNAME_STRING     0x0720
⍝#define IL_JPG_SAVE_FORMAT         0x0721
⍝#define IL_CHEAD_HEADER_STRING     0x0722
⍝#define IL_PCD_PICNUM              0x0723

⍝ Image-specific constants
⍝#define IL_IMAGE_WIDTH           0x0DE4   = 3556
⍝#define IL_IMAGE_HEIGHT          0x0DE5   = 3557
⍝#define IL_IMAGE_DEPTH           0x0DE6   = 3558
⍝#define IL_IMAGE_SIZE_OF_DATA    0x0DE7   = 3559
⍝#define IL_IMAGE_BPP             0x0DE8   = 3560
⍝#define IL_IMAGE_BYTES_PER_PIXEL 0x0DE8
⍝#define IL_IMAGE_BITS_PER_PIXEL  0x0DE9   = 3561
⍝#define IL_IMAGE_FORMAT          0x0DEA   = 3562
⍝#define IL_IMAGE_TYPE            0x0DEB   = 3563

⍝#define IL_PALETTE_TYPE          0x0DEC   = 3564
⍝#define IL_PALETTE_SIZE          0x0DED   = 3565
⍝#define IL_PALETTE_BPP           0x0DEE   = 3566
⍝#define IL_PALETTE_NUM_COLS      0x0DEF   = 3567
⍝#define IL_PALETTE_BASE_TYPE     0x0DF0   = 3568

⍝ Image format constants
⍝#define IL_COLOUR_INDEX    0x1900  = 6400
⍝#define IL_RGB             0x1907  = 6407
⍝#define IL_RGBA            0x1908  = 6408
⍝#define IL_BGR             0x80E0  = 32992
⍝#define IL_BGRA            0x80E1  = 32993
⍝#define IL_LUMINANCE       0x1909  = 6409 (default/reported when error)
⍝#define IL_LUMINANCE_ALPHA 0x190A  = 6410

⍝ Image types/pixel component size constants
⍝#define IL_BYTE            0x1400  = 5120
⍝#define IL_UNSIGNED_BYTE   0x1401  = 5121
⍝#define IL_SHORT           0x1402  = 5122
⍝#define IL_UNSIGNED_SHORT  0x1403  = 5123
⍝#define IL_INT             0x1404  = 5124
⍝#define IL_UNSIGNED_INT    0x1405  = 5125
⍝#define IL_FLOAT           0x1406  = 5126
⍝#define IL_DOUBLE          0x140A  = 5130

⍝ Palette type contants
⍝#define IL_PAL_NONE        0x0400  = 1024
⍝#define IL_PAL_RGB24       0x0401  = 1025
⍝#define IL_PAL_RGB32       0x0402  = 1026
⍝#define IL_PAL_RGBA32      0x0403  = 1027
⍝#define IL_PAL_BGR24       0x0404  = 1028
⍝#define IL_PAL_BGR32       0x0405  = 1029
⍝#define IL_PAL_BGRA32      0x0406  = 1030

⍝ Animation constants
⍝#define IL_NUM_IMAGES      0x0DF1  = 3569
⍝#define IL_ACTIVE_IMAGE    0x0DF4  = 3572
⍝#define IL_IMAGE_DURATION  0x0DF8  = 3576
⍝ ILboolean ilActiveImage(ILuint ImageNum);
⍝ ActiveImage is functionally equivalent to ActiveMipmap, except that it deals with animations and not mipmaps
⍝ ActiveImage can ONLY step forwards, the image specified always relative to the current
 REF.⎕NA'I DevIL|ilActiveImage U4'

⍝ ILubyte* ilGetPalette(ILvoid);
 REF.⎕NA'I DevIL|ilGetPalette' ⍝ All DevIL returns is a measly pointer! MEMCPY the only way to go, *sigh*
 'CopyPalette'REF.⎕NA'dyalog32|MEMCPY >U1[] I4 U4' ⍝ So, MEMCPY the palette into the session

⍝ ILboolean ilConvertImage(ILenum DestFormat, ILenum DestType);
 REF.⎕NA'I DevIL|ilConvertImage U4 U4'  ⍝ See above for enums

⍝ ILboolean ilConvertPal(ILenum DestFormat);
 REF.⎕NA'I DevIL|ilConvertPal U4'       ⍝ See above for palette type constants

⍝ ILboolean iluNegative(ILvoid);
 REF.⎕NA'I ILU|iluNegative'

⍝ ILboolean iluGammaCorrect(ILfloat Gamma);
 REF.⎕NA'I ILU|iluGammaCorrect F4'

⍝ ILvoid iluGetImageInfo(ILinfo *Info);
 REF.⎕NA'ILU|iluGetImageInfo >0T[]'

⍝ ILvoid iluImageParameter(ILenum PName, ILenum Param);
 REF.⎕NA'ILU|iluImageParameter U4 U4'
⍝ Parameters:
⍝#define ILU_FILTER         0x2600  = 9728
⍝ Filters/methods for resizing:
⍝#define ILU_NEAREST        0x2601  = 9729 \
⍝#define ILU_LINEAR         0x2602  = 9730  | OK for all images, also indexed
⍝#define ILU_BILINEAR       0x2603  = 9731 /
⍝#define ILU_SCALE_BOX      0x2604  = 9732 \
⍝#define ILU_SCALE_TRIANGLE 0x2605  = 9733  |
⍝#define ILU_SCALE_BELL     0x2606  = 9734  | Works only for RGB images
⍝#define ILU_SCALE_BSPLINE  0x2607  = 9735  |
⍝#define ILU_SCALE_LANCZOS3 0x2608  = 9736  |
⍝#define ILU_SCALE_MITCHELL 0x2609  = 9737 /

⍝ ILboolean iluScale(ILuint Width, ILuint Height, ILuint Depth);
 REF.⎕NA'I ILU|iluScale U4 U4 U4'

⍝ ILboolean iluRotate(ILfloat Angle);
 REF.⎕NA'I ILU|iluRotate F4'            ⍝ Rotate degrees anti-clockwise

⍝ ILenum ilGetError(ILvoid);
 REF.⎕NA'U4 DevIL|ilGetError'

⍝ const char* iluErrorString(ILenum Error);
 REF.⎕NA'I ILU|iluErrorString U4'
 'CopyErrorMessage'REF.⎕NA'dyalog32|STRNCPY >0T[] I4 U4'

 dummy←REF.ilInit
 dummy←REF.iluInit
 REF.jpegQuality←REF.ilGetInteger 1809  ⍝ Used when saving image in JPEG format

 pxl←EncodeRGB rgb
⍝ Encodes a 3D matrix with RGB pixel data for use by Cbits
 pxl←0 0⍴0
 →(~3∊⍴rgb)/0 ⍝ Make sure that at least one axis has length 3
 rgb←2 3 1⍉rgb
 pxl←256⊥rgb

 rgb←DecodeRGB pxl
⍝ Decodes a 2D Cbits matrix to 3D RGB pixel component data
 rgb←3 1 2⍉256 256 256⊤pxl ⍝ This gives the proper ravel order

 ErrorHandler ok;err;err_msg
⍝ Checks for errors returned from calls to DevIL
⍝ Possible error codes are in the range 0x0501-0x05FF
⍝ whereas for Dyalog user-defined errors are 500-999
 →(1=ok)/0
 err←ilGetError
 :If 0≠err
     err_msg←CopyErrorMessage 100(iluErrorString err)100
     err_msg ⎕SIGNAL err-780 ⍝ "Lower" the error code into the range of Dyalog user-defined errors
 :EndIf

 size←GetSize
⍝ Returns size of image in DevIL

 size←ilGetInteger¨3557 3556 ⍝ Image height and width (pixels)
⍝ #define IL_IMAGE_WIDTH           0x0DE4  = 3556 (pixels)
⍝ #define IL_IMAGE_HEIGHT          0x0DE5  = 3557 (pixels)
⍝ #define IL_IMAGE_DEPTH           0x0DE6  = 3558 (pixels)
⍝ #define IL_IMAGE_SIZE_OF_DATA    0x0DE7  = 3559 (bytes)
⍝ #define IL_IMAGE_BPP             0x0DE8  = 3560
⍝ #define IL_IMAGE_BYTES_PER_PIXEL 0x0DE8
⍝ #define IL_IMAGE_BITS_PER_PIXEL  0x0DE9  = 3561

 format←GetFormat;sformat
⍝ Returns format of image ALREADY LOADED in DevIL, e.g. by Load

 format←ilGetInteger 3562 ⍝ Image format
 :Select format
 :Case 6400     ⍝#define IL_COLOUR_INDEX    0x1900  = 6400
     sformat←'Indexed/palette'
 :Case 6407     ⍝#define IL_RGB             0x1907  = 6407
     sformat←'RGB'
 :Case 6408     ⍝#define IL_RGBA            0x1908  = 6408
     sformat←'RGB+α'
 :Case 32992    ⍝#define IL_BGR             0x80E0  = 32992
     sformat←'BGR'
 :Case 32993    ⍝#define IL_BGRA            0x80E1  = 32993
     sformat←'BGR+α'
 :Case 6409     ⍝#define IL_LUMINANCE       0x1909  = 6409 (default/reported when error)
     sformat←'Luminace'
 :Case 6410     ⍝#define IL_LUMINANCE_ALPHA 0x190A  = 6410
     sformat←'Luminace+α'
 :EndSelect

 r←GetBits;depth;err;format;height;img;nbytes;ntype;size;type;width
⍝ Retreives pixels from image in DevIL
⍝ Returns: error message or pixel matrix
 width←ilGetInteger 3556  ⍝ Image width (pixels)
 height←ilGetInteger 3557 ⍝ Image height (pixels)
 depth←ilGetInteger 3558  ⍝ Image depth (pixels)
 format←GetFormat         ⍝ Image format
 type←ilGetInteger 3563   ⍝ Image type/pixel component size
 nbytes←ilGetInteger 3559 ⍝ Size of bulk data
 size←height width

 err img←ilCopyPixels 0 0 0 width height depth format type nbytes
 ErrorHandler err

 :Select format       ⍝ Image format
 :CaseList 6400 6409  ⍝ Indixed or grey scale (luminance) image
     img←size⍴img     ⍝ Put some structure to the bulky data
 :CaseList 6407 32992 ⍝ RGB or BGR
     img←(size,3)⍴img ⍝ Put some structure to this bulky data
     :If format∊32992 32993
         img←⌽img     ⍝ Convert BGR to RGB
     :EndIf
     img←2 3 1⍉img    ⍝ Restructure for "encode"
     img←256⊥img
 :Case 6410           ⍝ Grey scale with ¸-channel
     img←(size,2)⍴img ⍝ Put some structure to the bulky data
     img←⊃¨1↓[3]img   ⍝ For now, just discard the ¸-channel
 :CaseList 6408 32993 ⍝ RGB or BGR, with α-channel
     img←(size,4)⍴img ⍝ Put some structure to this bulky data
     img←3↑[3]img     ⍝ For now, just discard the α-channel
     :If format∊32992 32993
         img←⌽img     ⍝ Convert BGR to RGB
     :EndIf
     img←2 3 1⍉img    ⍝ Restructure for "encode"
     img←256⊥img
 :EndSelect
 r←img

 cmap←GetCMap;dummy;format;img;PAL
⍝ Retreives palette from image in DevIL
⍝ Returns: Error message or cmap
 cmap←0 3⍴0

 format←GetFormat
 :If format≠6400
 ⍝ No palette to return
     →0
 :EndIf

 'PAL'⎕NS''
⍝#define IL_PALETTE_TYPE       0x0DEC  = 3564
⍝#define IL_PALETTE_SIZE       0x0DED  = 3565
⍝#define IL_PALETTE_BPP        0x0DEE  = 3566
⍝#define IL_PALETTE_NUM_COLS   0x0DEF  = 3567
⍝#define IL_PALETTE_BASE_TYPE  0x0DF0  = 3568
⍝#define IL_PAL_NONE           0x0400  = 1024
⍝#define IL_PAL_RGB24          0x0401  = 1025
⍝#define IL_PAL_RGB32          0x0402  = 1026
⍝#define IL_PAL_RGBA32         0x0403  = 1027
⍝#define IL_PAL_BGR24          0x0404  = 1028
⍝#define IL_PAL_BGR32          0x0405  = 1029
⍝#define IL_PAL_BGRA32         0x0406  = 1030
 PAL.type←ilGetInteger 3564   ⍝ Palette type
 PAL.size←ilGetInteger 3565   ⍝ Palette size
 PAL.bpp←ilGetInteger 3566    ⍝ Palette "bytes per pixel"
 PAL.ncols←ilGetInteger 3567  ⍝ Palette number of cols
 PAL.btype←ilGetInteger 3568  ⍝ Palette base type ???
 PAL.nbytes←PAL.bpp×PAL.ncols ⍝ Number of bytes in Cmap
 PAL.handle←ilGetPalette      ⍝ All DevIL gives us is a bloody pointer!
 cmap←CopyPalette PAL.nbytes PAL.handle PAL.nbytes
 :Select PAL.type
 :Case 1024
     ⍝ Huh? No palette? That's a mistake!
 :CaseList 1025 1028            ⍝ 24-bits palette
     cmap←PAL.ncols 3⍴cmap
 :CaseList 1027 1030            ⍝ 32-bits palette with α-channel
     cmap←3↑[2]PAL.ncols 4⍴cmap ⍝ For now, just discard the α-channel
 :CaseList 1026 1029
     ⍝ 32-bit colours... Don't know the format of those
     ⍝ Must somehow be converted to 24-bits in order for Dyalog to accept them
 :EndSelect
 :If PAL.type∊1028 1030 ⋄ cmap←⌽cmap ⋄ :EndIf ⍝ Convert BGR to RGB

 r←GetCBits;format;palette;pixels
⍝ Just like GetBits but converts any palette to RGB
 pixels←GetBits

 format←GetFormat              ⍝ Image format
 :Select format
 :Case 6400     ⍝#define IL_COLOUR_INDEX  0x1900  = 6400
     palette←GetCMap           ⍝ Acquire palette
     pixels←palette[1+pixels;] ⍝ Convert to cbits
     pixels←EncodeRGB pixels
 :Case 6409     ⍝#define IL_LUMINANCE       0x1909  = 6409 (default/reported when error)
     palette←3/,[1.5]¯1+⍳256   ⍝ Generate a grey scale palette
     pixels←palette[1+pixels;] ⍝ Convert to cbits
     pixels←EncodeRGB pixels
 :EndSelect
 r←pixels

 Set data;bpp;bits;cmap;err;fmt;max;type
⍝ Sets up an image in DevIL
⍝ Takes: bits or bits+cmap

⍝ So far supports following formats:
⍝ B/W: byte, short/word
⍝ Colour: 256/palette, 3-byte RGB
⍝ So far no support for: 4-byte RGB, α-channel in general

 :Select data
 :Case 1
     bits←data ⋄ cmap←0 3⍴0
 :Case 2
     bits cmap←data
 :EndSelect

 max←⌈/⌈/bits
 bpp←+/0 255 32767<max
 type←(1+max>255)⊃5121 5123 ⍝ IL_UNSIGNED_BYTE IL_UNSIGNED_SHORT

 :If 0=⊃⍴cmap
 ⍝ No palette -> pixels are B/W or RGB
     :If max≤32767 ⍝ 8-bits and 16-bits are considered B/W
         fmt←6409  ⍝ IL_LUMINANCE
     :Else
         ⍝ 24-bits is considered RGB
         fmt←6407  ⍝ IL_RGB
         type←5121 ⍝ IL_UNSIGNED_BYTE
         bits←DecodeRGB bits ⍝ Split the Cbits in RGB components
     :EndIf
 :Else
 ⍝ Palette -> check that indices are within range
     fmt←6400 ⍝ IL_COLOUR_INDEX
     :If max>¯1+⊃⍴cmap
         'bits out of cmap range'⎕SIGNAL 3
     :EndIf
 :EndIf

 ⍝ Now, copy pixel values to DevIL
 →(~type∊5120 5121)/0 ⍝ So far only byte-sized components are supported
 ⍝ ILboolean ilTexImage(ILuint Width, ILuint Height, ILuint Depth, ILubyte Bpp, ILenum Format, ILenum Type, ILvoid *Data);
 ErrorHandler ilTexImage(⌽2↑⍴bits),1 bpp fmt type((,⊖bits),,cmap)
 ⍝ilSetData
 ⍝ilSetPixels

 Load fn
⍝ Loads an image from file fn into instance of DevIL
⍝ Does NOT load image into ws but keeps it in the DLL

 ErrorHandler ilLoadImage⊂fn

 'PAL'⎕NS'' ⋄ PAL.type←1024       ⍝ Default empty palette
 :If GetFormat=6400  ⍝ Indixed image
     PAL.type←ilGetInteger 3564   ⍝ Palette type
     PAL.bpp←ilGetInteger 3566    ⍝ Palette "bytes per pixel"
     PAL.ncols←ilGetInteger 3567  ⍝ Palette number of cols
     PAL.nbytes←PAL.bpp×PAL.ncols ⍝ Number of bytes in "Cmap"
 :EndIf
 :Select PAL.type
 :Case 1024     ⍝#define IL_PAL_NONE   0x0400  = 1024
     PAL.stype←'None'
 :Case 1025     ⍝#define IL_PAL_RGB24  0x0401  = 1025
     PAL.stype←'RGB24'
 :Case 1026     ⍝#define IL_PAL_RGB32  0x0402  = 1026
     PAL.stype←'RGB32'
 :Case 1027     ⍝#define IL_PAL_RGBA32 0x0403  = 1027
     PAL.stype←'RGBα32'
 :Case 1028     ⍝#define IL_PAL_BGR24  0x0404  = 1028
     PAL.stype←'BGR24'
 :Case 1029     ⍝#define IL_PAL_BGR32  0x0405  = 1029
     PAL.stype←'BGR32'
 :Case 1030     ⍝#define IL_PAL_BGRA32 0x0406  = 1030
     PAL.stype←'BGRα32'
 :EndSelect

 {type_ext}Save fn;_
⍝ Saves image, which is currently in DLL
⍝ DLL determines image file format from file name extension
⍝ If type_ext is supplied then it overrules the file name extension

 _←ilSetInteger 1809(˜jpegQuality) ⍝ Transfer JPEG image file format quality to DLL
 :If 0=⎕NC'type_ext'
    ⍝ ILboolean ilSaveImage(const char *FileName);
     ErrorHandler ilSaveImage⊂fn ⍝ Determines image format from the file extension
 :Else
⍝                  BMP  JPEG PCX  PSD  PNG  PNM  SGI  TGA  TIFF C-h  Raw  DDS  Jasc-pal
     :If ~type_ext∊1056 1061 1064 1065 1066 1067 1068 1069 1070 1071 1072 1079 1141
         type_ext←0 ⍝ Unknown type
     :EndIf
    ⍝ ILboolean ilSave(ILenum Type, const char *FileName);
     ErrorHandler ilSave type_ext fn
 :EndIf

⍝ Image file formats valid for saving:
⍝#define IL_TYPE_UNKNOWN 0x0000
⍝#define IL_BMP      0x0420  = 1056  Windows & OS/2 bitmap
⍝#define IL_CHEAD    0x042F  = 1071  C-style header (.h)
⍝#define IL_DDS      0x0437  = 1079  DirectX DirectDraw Surface
⍝#define IL_JPG      0x0425  = 1061
⍝#define IL_PCX      0x0428  = 1064  ZSoft PCX
⍝#define IL_PNG      0x042A  = 1066  Portable Network Graphics
⍝#define IL_PNM      0x042B  = 1067  Portable AnyMap (.pbm, .pgm or .ppm)
⍝#define IL_PSD      0x0439  = 1065  Adobe Photo Shop
⍝#define IL_RAW      0x0430  = 1072  Raw dump of image data
⍝#define IL_SGI      0x042C  = 1068  Silicon Graphics IRIS Graphic File (.bw, .rgb, .rgba or .sgi)
⍝#define IL_TGA      0x042D  = 1069  TrueVision Targa
⍝#define IL_TIF      0x042E  = 1070  Tagged image file format
⍝#define IL_JASC_PAL 0x0475 = 1141 Paint Shop Pro (Jasc) palette (.pal)

⍝ The following not mentioned in the manual as valid for saving:
⍝#define IL_CUT       0x0421
⍝#define IL_DOOM      0x0422
⍝#define IL_DOOM_FLAT 0x0423
⍝#define IL_ICO       0x0424
⍝#define IL_JFIF      0x0425
⍝#define IL_LBM       0x0426
⍝#define IL_PCD       0x0427
⍝#define IL_PIC       0x0429
⍝#define IL_MDL       0x0431
⍝#define IL_WAL       0x0432
⍝#define IL_LIF       0x0434
⍝#define IL_MNG       0x0435
⍝#define IL_JNG       0x0435
⍝#define IL_GIF       0x0436
⍝#define IL_DCX       0x0438
⍝#define IL_EXIF      0x043A
⍝#define IL_PSP       0x043B
⍝#define IL_PIX       0x043C
⍝#define IL_PXR       0x043D
⍝#define IL_XPM       0x043E

 {method}Resize new_size;arg;dummy;err;method
⍝ Resizes an image that has ALREADY BEEN LOADED into DevIL, using e.g. Load
⍝ new_size: Vector with 2 or 3 elements, specifying the new size (z×)y×x
⍝ method: Filter to use when performing the resizing (see the DevIL manual)

⍝ If OpenIL refuses to do a scaling, returning "illegal operation"
⍝ try converting the image to RGB, calling ilConvertImage

⍝ Check validity of argument
 :If 0=⎕NC'method' ⋄ method←9731 ⋄ :EndIf
 :If ~method∊9729 9730 9731 9732 9733 9734 9735 9736 9737
     method←9731
 :EndIf

⍝ Resizing with filters ≥9732 requires image to be in RGB format
 :If method≥9732
 :AndIf 6400=GetFormat
⍝#define IL_COLOUR_INDEX    0x1900  = 6400
     'selected method/filter can resize full colour images only, call e.g. ilConvertImage 6407 GetType'⎕SIGNAL 11
 :EndIf

⍝ First set the method to use for the resizing. The fancy ones don't work with indexed images...
 dummy←iluImageParameter 9728 method
⍝#define ILU_FILTER         0x2600  = 9728
⍝ Filters/methods for resizing:
⍝#define ILU_NEAREST        0x2601  = 9729 \
⍝#define ILU_LINEAR         0x2602  = 9730  | OK for all images, also indexed
⍝#define ILU_BILINEAR       0x2603  = 9731 /
⍝#define ILU_SCALE_BOX      0x2604  = 9732 \
⍝#define ILU_SCALE_TRIANGLE 0x2605  = 9733  |
⍝#define ILU_SCALE_BELL     0x2606  = 9734  | Works only on RGB images
⍝#define ILU_SCALE_BSPLINE  0x2607  = 9735  |
⍝#define ILU_SCALE_LANCZOS3 0x2608  = 9736  |
⍝#define ILU_SCALE_MITCHELL 0x2609  = 9737 /

 ErrorHandler iluScale 3↑(⌽new_size),1 1 1 ⍝ DON'T suppress any axes! It makes DevIL unstable!

Getting started

The following functions don't need to go in the DevIL namespace; they just make use of it:

 data←FileRead fn;bits;cmap;err_msg;img
⍝ Calls DevIL to load image from file fn
⍝ Returns: error msg, bits, cmap (empty in case of RGB)

⍝ Supported types:
⍝ BMP CUT DCX DDS EXIF GIF ICO JNG JPEG LBM LIF LMP/Doom MDL/Half Life
⍝ MNG PBM PCD PCX PGM PIC PIX PNG PNM PPM PSD PSP PXR RAW SGI TGA TIFF WAL XPM

 err_msg←'' ⋄ bits←0 0⍴0 ⋄ cmap←0 3⍴0
 IMG←New
 err_msg←IMG.Load fn
 →(0<⊃⍴err_msg)/exit
 bits←IMG.GetBits
 →(2≠⍴⍴bits)/exit
 cmap←IMG.GetCMap
exit:
 data←err_msg bits cmap

 err_msg←data FileWrite fn;bits;cmap;IMG
⍝ Calls DevIL to save image to file fn
⍝ Takes: bits, cmap
⍝ Returns: error msg

⍝ Supported types:
⍝ BMP DDS h/C-header JPG PAL/Jasc PBM PCX PGM PNG PNM PPM PSD RAW SGI TGA TIFF

 :If 2≠⊃⍴data ⋄ err_msg←'invalid argument' ⋄ →exit ⋄ :EndIf
 bits cmap←data
 :If 2≠⍴⍴bits ⋄ err_msg←'invalid argument' ⋄ →exit ⋄ :EndIf
 :If 2≠⍴⍴cmap ⋄ err_msg←'invalid argument' ⋄ →exit ⋄ :EndIf

 IMG←New
 err_msg←IMG.Set bits cmap
 →(0<⊃⍴err_msg)/exit
 err_msg←IMG.Save fn
 →(0<⊃⍴err_msg)/exit
 err_msg←''
exit:

This DevIL "object" can now be used to read and write image files to and from the APL workspace.

err bits cmap←#.DevIL.FileRead filename
err←bits cmap #.DevIL.FileWrite filename

Deploying OpenIL

The OpenIL is perfectly capable of keeping and handling the image data itself, which the "object approach" makes very easy.

Image data in and out

An image is accessed in the following way

IMG←#.DevIL.New
IMG.Load 'photo.jpg'
bits←img.GetBits
cmap←img.GetCMap
cbits←img.GetCBits
img.GetSize

Manipulation of image data

An image can be resized at will – specifying the method is optional:
IMG.Resize 200 320
... and rotated:
IMG.iluRotate ¯5.5

CategoryWorkInProgress