| DrawImage | ||
|
|
||
| Contents | ||||||
|
||||||
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 | |||
| InitDrawImage | Initializes DrawImage for use. Required before DrawImage methods can be called. | ||
| KillDrawImage | Disposes all resources allocated and objects created. Called automatically when the Draw object is destroyed. | ||
| diReadImage | Load an image from disk, resource or BLOB into the control. Supports a wide variety of file formats. | ||
| diWriteImage | Saves the image in almost two different file formats including JPEG, PNG, TIFF, BMP, ICO, PBM, Targa, JPEG2000 etc. | ||
| diImageFromCache | Loads an image from the internal Draw image cache (by default Draw caches images loading for increased performance when images are reused) | ||
| diGetImageInfo | Retrieve the image information (width, height etc.) from a file on disk | ||
| diReadImageToBuffer | Reads an image file into a buffer | ||
| diImageFromBuffer | Writes an image from a buffer to the current layer | ||
DrawImage Method Reference
Click on the
(up)
icon to go back to the layer Method Index.
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
fName
The name of the file to load. If the imageBlob parameter is passed this can
be an empty string (it will be ignored).
x
The x (horizontal) coordinate to place the image at. The number of pixels
from the left hand side of the Draw control.
y
The 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 performns 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
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 (string fileName, long long fileFormat=-1), bool, proc
Writes the current Draw image to large variety of image formats. Defaults to saving the image as a PNG.
Parameters
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 Procedure (string fName, *long w, *long h, *string imageBuffer, *long zPad, real fAngle=0, <*blob imageBlob>)
Loads an image from disk (or a BLOB) into a string in memory.
Parameters
fName
The 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.
w
If 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.
h
If 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.
imageBuffer
A 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).
zPad
Set 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 Procedure (*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)
Draws an image from the specified buffer (typically loaded by calling diReadImageToBuffer) using the specified paremeters. Supports clipping, tiling (and combining clipping and tiling to fill a rectangular area with a tiled pattern of images) etc.
Parameters
x
The x (horizontal) coordinate to place the image at. The number of pixels from the left hand side of the Draw control.
y
The 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.
height
The 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).
zeroPadding
The 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.
