SHIP:Sail:image

Function	Returns	Introduced	Description
image	Integer	v5.1.2	Display an image

See Also:

• Sail Home
• Sail Functions
• Sail Numeric Functions
• draw, qr

Prototype

Integer err = image(Node canvas, Node file, Integer result[, Integer posX, Integer posY, Integer offsetX, Integer offsetY, Integer clipW, Integer clipH]);

Parameters/Return Value

Parameter	Data Type	Description
canvas	Node	Canvas to draw on
file	Node	file node of JPEG file name in 8.3 format
result	Integer	Deferred result of the rendering action
posX	Integer	X coordinate on canvas
posY	Integer	y coordinate on canvas
offsetX	Integer	x offset to place image
offsetY	Integer	y offset to place image
clipW	Integer	image width
clipH	Integer	image height
Return	Integer	error code if job was successfully scheduled or not

Detailed Description

This function takes the image pointed to by the string file and displays it on the canvas in the location resolved by position and offset. The image will be clipped according to the clip arguments. Current allowed images are JPEG. An error code of 0 is successful job scheduled.

Create a listener listening to "result" in order to determine if the actual command succeeded.

Supported JPEG Image Features

Feature	Specifications
Elements of color	3 colors (YCbCr)
Ratio of sample	4:4:4 (1x1,1x1,1x1) 4:2:2 (2x1,1x1,1x1) 4:2:2 (1x2,1x1,1x1) 4:1:1 (2x2,1x1,1x1)
Input data	All data has to be prepared
Clipping of expansion	No support
Progressive	No support
Exif	No support

• An image with a size larger than the canvas will cause the image not to be rendered at all.
• Ensure that the Clipping of expansion, Progressive, and Exif options are disabled in the JPEG file with a tool such as GIMP or it will cause the file not to render.
• The JPEG file name must be in 8.3 format.

Example

Command Scheduling

Example	Results	Notes
err = image(homeCanvas, fKite, pResult, 0, 0, ow/2, oh/2, 0, 0);	0	The command is scheduled successfully to display the pic in the bottom right

Listener to pResult

Example	Results	Notes
if (pResult != 0) { <process error> };	0	The image was successfully displayed in the bottom right if pResult is 0