CapeSoft DrawImage
Documentation

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).
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 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 drawer.BestFit(imageWidth, imageHeight, drawer.width, drawer.height, imageWidth, imageHeight) !--- display the image centered on the canvas 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

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 (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
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 (*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
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.