From Serious Documentation
Jump to: navigation, search
Function Returns Introduced Description
image Integer v5.1.2 Display an image

See Also:


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
  • 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.


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