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

Notes

• Any combination of posX, posY, offsetX, offset, clipW, clipH or canvas size causing any portion of the image to be clipped will cause the image not to be rendered at all.
• Since the image() call is performed in a separate thread from the GUI, if the canvas the image is being rendered into is an object of a currently visible node, any renders that occur due to changes in the GUI prior to the rendering of the image being completed could result in an incomplete render being seen temporarily.
• The image() call is not able to cause the node with the canvas being rendered into as its object to be dirtied and re-rendered, due to this it is good practice to toggle the visible property false->true of the node that has the canvas as it’s object in order to ensure the GUI is re-rendered.
• Attempting to use other canvas draw commands with a canvas while an image() call is in progress can produce undefined results.
• Calls to image() while another image() call is in progress causes them to be queued in order of submission, it is possible the number of queued calls can be exceeded and an attempt to schedule one could be denied. If queuing calls, it’s important to build logic that can account for this by checking the return value of the call and further queuing future calls through some GUI implemented methodology.
• 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