CapeSoft.Com
Clarion Accessories
Draw
Documentation
DrawImage
CapeSoft Logo

CapeSoft DrawImage
Documentation

Installed Version Latest Version
Download Latest Version JumpStart FAQ History

The DrawImage Methods

DrawImage is a new set of methods for the existing Draw class. These methods leverage the open source FreeImage library and integrate it with Draw. This provides the ability to load and save additional formats such as JPEG, PNG, TIFF and so on, as well as providing the ability to rotate, scale, shear and otherwise manipulate images. In addition there are a number of new Draw methods that enhance this functionality by providing features not found in FreeImage, such as colour control, conversion to grayscale, automatic image resizing, image tiling and clipping and so on.

Please note that this documentation is under construction and is being expanded.

Getting Started

Using DrawImage is as simple as ticking the Enable DrawImage tickbox on the global extension

"DrawImage" Draw Class Methods


DrawImage Methods in the Draw class
InitDrawImageInitializes DrawImage for use. Required before DrawImage methods can be called.
KillDrawImageDisposes all resources allocated and objects created. Called automatically when the Draw object is destroyed.
diReadImageLoad an image from disk, resource or BLOB into the control. Supports a wide variety of file formats.
diWriteImageSaves the image in almost two different file formats including JPEG, PNG, TIFF, BMP, ICO, PBM, Targa, JPEG2000 etc.
diImageFromCacheLoads an image from the internal Draw image cache (by default Draw caches images loading for increased performance when images are reused)
diGetImageInfoRetrieve the image information (width, height etc.) from a file on disk
diReadImageToBufferReads an image file into a buffer
diImageFromBufferWrites an image from a buffer to the current layer

DrawImage Method Reference

diReadImage

diReadImage (string fName, long x, long y, long w=0, long h=0, long tileFlag=0, long maxVertTiles=0, long maxHorizTiles=0, real fAngle=0, long indexColor=-1, <*blob imageBlob>)

Loads a large variety of image formats, and supports loading from disk (file), resource (compiled into the application) or BLOB. Supports BMP, PNG, JPEG, TIFF and more. This method also supports resizing (scaling), rotating and tiling of the image, as well as placing the image treating a specified colour as transparent.

Parameters
Parameter Description
fName The name of the file to load. If the imageBlob parameter is passed this can be an empty string (it will be ignored).
xThe x (horizontal) coordinate to place the image at. The number of pixels from the left hand side of the Draw control.
yThe y (vertical) coordinate to place the image at. The number of pixels from the top of the Draw control.
w [optional]The width of the image, pass this as 0 in order to use the actual width of the image. If a width is specified the image will be scaled to that width. Use the BestFit() method to calculate proportional resizing to maintain the aspect ratio while resizing the image to fit within a desired area.

Note: If tiling is used then this is the area to be tiled over using the image.
h [optional]The height height of the image, pass this as 0 in order to use the actual height of the image. If a height is specified the image will be scaled to that height. Use the BestFit() method to calculate proportional resizing to maintain the aspect ratio while resizing the image to fit within a desired area.

Note: If tiling is used then this is the area to be tiled over using the image.
tileFlag [optional] Flag for setting the tiling options. Valid values are 0 (zero) for no tiling; Draw:Tile (using tiling); Draw:TileHoriz (horizontal tiling only); or Draw:TileVert (vertical tiling only).
tilesVert [optional] Limits the number of times the image can be tiled vertically. Otherwise the image is tiled as many times as needed over the specified area, and clipped to fit.
tilesHoriz [optional] Limits the number of times the image can be tiled horizontally. Otherwise the image is tiled as many times as needed over the specified area, and clipped to fit.
Return Values

None. If the method fails it calls ErrorTrap() with an error description.

Remarks

Draw supports a number of methods for handling images in various manners. See the diReadImageToBuffer() method, which performs the same basic function, however it reads the image into a buffer which can then be written to the Draw control by calling diImageFromBuffer() at any time. This supports the same functionality, but allows the image to be stored and reused without loading it from disk, which provides dramatically improved performance when using the same image a number of times (this is the approach used internally to handle tiling).

Examples
Example
if not Drawer.useDrawImage
           Drawer.InitDrawImage()
end

Drawer.Blank(color:white)
i = Random(1, 13)
Drawer.diGetImageInfo(i & '.jpg', imageWidth, imageHeight, imageBitDepth, imageType)

!--- Calculate the best fit within the control, while maintaining the aspect ratio of the image

! BestFit(ulong srcW, ulong srcH, ulong maxW, ulong maxH, *ulong newW, *ulong newH)
drawer.BestFit(imageWidth, imageHeight, drawer.width, drawer.height, imageWidth, imageHeight)

!--- display the image centered on the canvas
! diReadImage(string fName, long x, long y, long w=0, long h=0, long tileFlag=0, |
         !           long maxVertTiles=0, long maxHorizTiles=0, <*blob imageBlob>)
drawer.diReadImage(i & '.jpg', 1 + (drawer.width-imageWidth)/2, |
                   1 + (drawer.height-imageHeight)/2, imageWidth, imageHeight)
drawer.Display()
Notes

This method calls diReadImageToBuffer to load the actual image data, and also caches read images in the .cache property, which is an array of draw:CacheBufferType groups which contain the loaded image (see below for the draw:CacheBufferType fields). The diImageFromBuffer method can be used to draw images that are cached (or loaded into a string or BLOB field by calling diReadImageToBuffer).

draw:CacheBufferType group,type
filename               string(255)
buffer                 &string
buffersize             long
zeropad                long
width                  long
height                 long
fangle                 real
                   end
See Also

InitDrawImage, BestFit, diReadImageToBuffer, diImageFromBuffer, diGetImageInfo

diWriteImage

diWriteImage (string fileName, long long fileFormat=-1), bool, proc

Description

Writes the current Draw image to large variety of image formats. Defaults to saving the image as a PNG.

Parameters
Parameter Description
fileName The name of the file to write to.
fileFormat [optional]The file format to save the image as. Default to PNG. Can be any one of the following values:

FIF_UNKNOWN Equate(-1)
FIF_BMP Equate(0)
FIF_ICO Equate(1)
FIF_JPEG Equate(2)
FIF_JNG Equate(3)
FIF_KOALA Equate(4)
FIF_LBM Equate(5)
FIF_IFF Equate(FIF_LBM)
FIF_MNG Equate(6)
FIF_PBM Equate(7)
FIF_PBMRAW Equate(8)
FIF_PCD Equate(9)
FIF_PCX Equate(10)
FIF_PGM Equate(11)
FIF_PGMRAW Equate(12)
FIF_PNG Equate(13)
FIF_PPM Equate(14)
FIF_PPMRAW Equate(15)
FIF_RAS Equate(16)
FIF_TARGA Equate(17)
FIF_TIFF Equate(18)
FIF_WBMP Equate(19)
FIF_PSD Equate(20)
FIF_CUT Equate(21)
FIF_XBM Equate(22)
FIF_XPM Equate(23)
FIF_DDS Equate(24)
FIF_GIF Equate(25)
FIF_HDR Equate(26)
FIF_FAXG3 Equate(27)
FIF_SGI Equate(28)
FIF_EXR Equate(29)
FIF_J2K Equate(30)
FIF_JP2 Equate(31)
FIF_PFM Equate(32)
Return Value

Returns True (1) for success and False (0) for failure.

diReadImageToBuffer

diReadImageToBuffer (string fName, *long w, *long h, *string imageBuffer, *long zPad, real fAngle=0, <*blob imageBlob>

Description

Loads an image from disk (or a BLOB) into a string in memory.

Parameters
Parameter Description
fNameThe name of the file to load. Should contain the path of the image unless the image is in the directory specified by the current application path.
wIf this is set to zero then the image width is not changed loading (if w and h are both zero no resizing is done), otherwise it is resized if required using this as the width (no resizing is done if the passed w and h and equal to the width and height of the image loaded). On return the width of the image is stored in this parameter.
hIf this is set to zero then the image is height is not changed when loading (if w and h are both zero no resizing is done), otherwise it is resized if required using this as the height  (no resizing is done if the passed w and h and equal to the width and height of the image loaded). On return the height of the image is stored in this parameter.
imageBufferA string to contain the image data loaded. Must be large enough to contain the loaded (and optionally resized) image. This requires at least 3 bytes per pixel plus a 54 bytes header and up to three bytes of padding per scanline (row of pixels in the image, i.e. up to 3 * height bytes).
zPadSet to the amount of zero padding on the end of each row of pixels in the stored bitmap.  Zero padding ranges from 0 (no padding) to 3 (3 bytes per row).
fAngle [optional]The angle to rotate the image by when loading. Defaults to 0 (no rotation). Note that rotation changes the size and aspect ratio of the image.
imageBlob [optional]If this is passed then the image is loaded from this BLOB rather than from disk. This can be used to load images in any of the supported formats from any BLOB in any database independent of the backend (allows image files to be stored in tables rather than on disk).
Notes

This method is used internally by the diReadImage, which also caches read images in the .cache property, which is an array of draw:CacheBufferType group which contain the loaded image (see below for the draw:CacheBufferType fields). The diImageFromBuffer method can be used to draw images that are cached (or loaded into a string or BLOB field by calling diReadImageToBuffer).

draw:CacheBufferType group,type
filename               string(255)
buffer                 &string
buffersize             long
zeropad                long
width                  long
height                 long
fangle                 real
                   end

diImageFromBuffer

diImageFromBuffer (*string dataBuffer, long x, long y, long width, long height, long tileX=0, long tileY=0, long clipWidth=0, long clipHeight=0, long reverseColorBytes=0, long zeroPadding=0, long indexColor=-1)

Description

Draws an image from the specified buffer (typically loaded by calling diReadImageToBuffer) using the specified parameters. Supports clipping, tiling (and combining clipping and tiling to fill a rectangular area with a tiled pattern of images) etc.

Parameters
Parameter Description
xThe x (horizontal) coordinate to place the image at. The number of pixels from the left hand side of the Draw control.
yThe y (vertical) coordinate to place the image at. The number of pixels from the top of the Draw control.
width The width of the image in the passed buffer, in pixels. This must be the exact pixel width of the bitmap stored in the passed buffer.
heightThe height height of the image in the passed buffer, in pixels.
tileX [optional] The number of times to tile (repeat) the image horizontally.
tileY [optional] The number of times to tile (repeat) the image vertically.
clipWidth [optional]If specified then this is used as the width of the bounding rectangle for drawing the image. Anything outside of this (including when tiling) will not be drawn. The x and y coordinates in combination with clipWidth and clipHeight allow an image to be clipped to fit the specified bounding box, or to fill the bounding box when using the tiling options.
clipHeight [optional]If specified then this is used as the height of the bounding rectangle for drawing the image. Anything outside of this (including when tiling) will not be drawn.
reverseColorBytes [optional]If True (non zero) then the order of the color elements is reversed (allows drawing of both RGB and BGR order images).
zeroPaddingThe number of bytes of zero padding per row (scanline). While this defaults to zero (no zero padding) this should not be considered an optional parameter. The number of bytes of zero padding must be passed in non zero!
indexColor [optional]If this is specified (0 to 0FFFFFFh) then this color is treated as transparent and pixels of this color in the image are not drawn. Default to -1 (COLOR:NONE) which means that no index transparency is used and all pixels are drawn.
Return Value

Returns True for success and False for failure.