Drawings - lua module
This page describes special commands that are availble since changeset #1479, and are defined in drawings.lua module (A/CHDK/LUALIB/DRAWINGS.LUA).
Changeset #1479 bring a few Lua functions that provide a way do draw simple shapes on LCD screen from script (http://chdk.wikia.com/wiki/Lua/Lua_Reference#Drawings). This module enhances drawing procedure to give you more control in adding and removing shapes.
Initialization
Prior to use below commands one have to initialize drawings module. It is simple done by command:
require "drawings"
Note: Do not use .lua extention!
Objects
In this manual by object we will understand individual shape that has its own parameters, and can be added, removed, moved and changed. Objects that are available through this module are described in table:
Element | Element tape | Parameters |
---|---|---|
Pixel | pixel | x1, x2, color |
Line | line | x1, y1, x2, y2, color |
Rectangle | rect | x1, y1, x2, y2, color [, thickness] |
Filled Rectangle | rectf | x1, y1, x2, y2, color1, color2 [, thickness] |
Ellipse | elps | x, y, a, b, color |
Filled ellipse | elpsf | x, y, a, b, color1, color2 |
Text string | string | x, y, string, text_color, backgr_color |
parameteres in [ ] are not nessesery.
Creating of objects
Before you can draw and see your object you have to create it. To create an object you use following syntax:
draw.add("element_type", parameter1, parameter2....)
For example to create an empty rectangle which top-left corner have coordinates 10,50, bottom-right corner is at 220,200, which color is blue and thickness is 3 you have to use command:
draw.add("rect", 10, 50, 220, 200, "blue", 3)
Every time you use draw.add() function it returns a number, which is an identifier of newly created object. This value can be further used to change various parameters of the object. So you can get this value as follows:
my_line_id=draw.add("line", 45, 30, 100, 101, "red")
Now my_line_id keeps the identifier.
Drawing objects
Once you have created object(s) they are stored in memory, but they are not visible on the screen. To draw them you need to use one of the following commands:
draw.redraw()
or
draw.overdraw()
Both commands draw all objects on the screen. The difference is, that draw.redraw() first clears the screen, so you'll see only the new state, while draw.overdraw() draws new state but do not remove previous drawings. So if you moved an object and then used draw.overdraw() you'll see this object in both places.
Changing objects
You can change any of previous created objects if you have its identifier. To do so you use command:
draw.replace(id, "new_element_type", new_param1, new_param2...)
For example assume you have created filled rectangle:
my_rect=draw.add("rectf", 55, 104, 65, 114, "green", "yellow", 2)
and you like to move it 30 px to the right. You have to use:
draw.replace(my_rect_id, "rectf", 85, 104, 95, 114, "green", "yellow", 2)
Note that with draw.replace() you can change every parameters of the object. For example you can change above small rectangle into a big circle:
draw.replace(my_rect_id, "elps", 90, 110, 100, 100, "white")
Note also, that all these changes will not be visible untill you use draw.redraw() or draw.overdraw().
Removing objects
You can remove one specified object using command:
draw.remove(identifier)
You can also remove all objects using command:
draw.clear()
Note that this command removes objects from the screen as well as from memory. After this command you'l not have any of these objects.
Also note that simple Lua command draw_clear() is used to clear screen and it's not the same as draw.clear() from this module!
Getting parameters
If you know a identifier of an object you can get all its parameters as an array. Syntax:
params=draw.get_params(identifier)
For egzample:
params=draw.get_params(my_rect_id)
Variable params will now be an array with the following content:
{ "elps", 90, 110, 100, 100, "white" }
Colors
In above egzamples colors were used in ad explicit names. However, you can specify colors in two ways:
- With use of Canon firmware palette as numbers in a range 0-255. These numbers are not portable and the same number migh correspond to other color in othe camera (or even other mode). Also the same color will have different numerical value for different cameras. Use Canon firmware numbers only, if you need to have some specific tones fore specific camera.
- With use of CHDK script palette. Colors in this palette, that are used by drawings module are exactly the same as described in basic drawing Lua commands, just you don't use their numeric values but names. These names are as follows:
Basic colors:
trans black white red green blue
Extended colors:
red_dark red_light green_dark green_light blue_dark blue_light grey grey_dark grey_light yellow yellow_dark yellow_light
Basic colors should be available in most or all CHDK-supported cameras, since they are used by CHDK GUI and histogram. Extended colors are available only for cameras that use colored icons. If you use extended color in your script, camera which have no colored icons support will display the most similar color (e.g. green for green_light, white for yellow). Currently blue_light and blue_dark are only placeholders and they are not available in any camera!
Memory - SCREEN_DRAWINGS
It was said that when you create object it is stored in memory. In fact all these objects are stored in two-dimentional array named SCREEN_DRAWINGS. You can access this array directly, but using of drawings commands is prefered. If you use drawings module you can not use SCREEN_DRAWINGS name for any other pourposes, due to conflict. The other restricted word is draw. You should not use variables such as draw, draw[] and other derivatives.