Wikia

CHDK Wiki

Changes: Lua/Drawings

Edit

Back to page

(Manual for drawings module)
 
m (Memory - SCREEN_DRAWINGS)
 
(13 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=Drawings - lua module=
+
=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).
+
CHDK 1.2.0 and later <span style="font-size:13px;line-height:21px;"> </span><span style="font-size:13px;line-height:21px;">releases</span><span style="font-size:13px;line-height:21px;"> </span><span style="font-size:13px;line-height:21px;"> support Lua functions that draw simple shapes on your camera's LCD screen from a script.  See : </span>http://chdk.wikia.com/wiki/Lua/Lua_Reference#Drawings<span style="font-size:13px;line-height:21px;"> for a description of these functions.</span>
 
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.
 
   
  +
<span style="font-size:13px;line-height:21px;">There is also a Lua module that allows you to enhances these drawing functions, giving you more control in adding and removing shapes.  The primary advantage of using this module is that it allows you to easily and simply redraw (repaint) the shapes you have drawn  - something that proves necessary periodically as the Canon UI tends to overwrite things randomly.</span>
   
  +
<span style="font-size:13px;line-height:21px;">These functions are defined in drawings.lua module (A/CHDK/LUALIB/DRAWINGS.LUA).</span>
 
==Initialization==
 
==Initialization==
Prior to use below commands one have to initialize drawings module. It is simple done by command:
+
Prior to using the commands listed below, the drawings module has to be initialized with this simple command:
 
require "drawings"
 
require "drawings"
Note: Do not use .lua extention!
+
Note: Do not use .lua extension.
  +
 
==Objects==
 
==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:
+
In this manual ''object'' is understood as an individual shape with its own parameters, which can be added, removed, moved or changed. Objects that are available through this module are as follows:
 
{| border="1" cellpadding="1" cellspacing="1" style="width: 500px; "
 
{| border="1" cellpadding="1" cellspacing="1" style="width: 500px; "
 
! scope="col"|Element
 
! scope="col"|Element
! scope="col"|Element tape
+
! scope="col"|Element type
 
! scope="col"|Parameters
 
! scope="col"|Parameters
 
|-
 
|-
Line 42: Line 44:
 
| style="text-align: center; "|x, y, string, text_color, backgr_color
 
| style="text-align: center; "|x, y, string, text_color, backgr_color
 
|}
 
|}
parameteres in [ ] are not nessesery.
+
Parameters in [] are not necessary.
==Creating of objects==
+
Before you can draw and see your object you have to create it. To create an object you use following syntax:
+
==Creating objects==
  +
Before objects can be drawn or seen, they must be created. To create an object use following syntax:
 
draw.add("element_type", parameter1, parameter2....)
 
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:
+
For example, to create an empty rectangle whose top-left corner has the coordinates 10, 50, the bottom-right corner is at 220,200, the color is ''blue'' and line thickness is 3 use this command:
 
draw.add("rect", 10, 50, 220, 200, "blue", 3)
 
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:
+
Every time the ''draw.add()'' function is called it returns a number which identifies the newly created object. This value can be further used to change various parameters of the object. To obtain this value, use a variable, e.g. ''my_line_id'':
 
my_line_id=draw.add("line", 45, 30, 100, 101, "red")
 
my_line_id=draw.add("line", 45, 30, 100, 101, "red")
Now ''my_line_id'' keeps the identifier.
+
Now ''my_line_id'' stores the identifier.
  +
 
==Drawing objects==
 
==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:
+
Once objects have been created,they are stored in memory, but they are not visible on the screen. To draw them use either of the following commands:
 
draw.​redraw()
 
draw.​redraw()
 
or
 
or
 
draw.overdraw()
 
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.
+
Both commands draw all objects on the screen. The difference is that ''draw.redraw()'' first clears the screen, so only the new state visible, whereas ''draw.overdraw()'' draws new state but does not remove previous drawings. If an object is moved and then ''draw.overdraw()'' is called this object will appear in both places.
  +
 
==Changing objects==
 
==Changing objects==
You can change any of previous created objects if you have its identifier. To do so you use command:
+
Any previously created objects can be changed with reference to their identifiers. Use this command:
 
draw.replace(id, "new_element_type", new_param1, new_param2...)
 
draw.replace(id, "new_element_type", new_param1, new_param2...)
For example assume you have created filled rectangle:
+
For example, assume a filled rectangle has been created:
my_rect=draw.add("rectf", 55, 104, 65, 114, "green", "yellow", 2)
+
my_rect_id=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:
+
and you would like to move it 30 px to the right, using this coommand:
 
draw.replace(my_rect_id, "rectf", 85, 104, 95, 114, "green", "yellow", 2)
 
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:
+
Note that with ''draw.replace()'' every parameter of the object cam be changed. For example the small rectangle from above can be changed into a large circle:
 
draw.replace(my_rect_id, "elps", 90, 110, 100, 100, "white")
 
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()''.
+
Note also that all these changes will not be visible until ''draw.redraw() ''or ''draw.overdraw()'' are called.
  +
 
==Removing objects==
 
==Removing objects==
You can remove one specified object using command:
+
A specified object can be removed using:
 
draw.remove(identifier)
 
draw.remove(identifier)
You can also remove all objects using command:
+
All objects can be remoced by using:
 
draw.clear()
 
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.
+
Note that this command removes objects from the screen as well as from memory. After this command none of these objects will be accessible.
   
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!
+
Also note that simple Lua command ''draw_clear()'' is used to clear screen and is 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:
+
==Retrieving parameters==
  +
If the identifier of an object is known then all its parameters can be retrieved as an array. Syntax:
 
params=draw.get_params(identifier)
 
params=draw.get_params(identifier)
   
For egzample:
+
For example:
 
params=draw.get_params(my_rect_id)
 
params=draw.get_params(my_rect_id)
 
Variable ''params'' will now be an array with the following content:
 
Variable ''params'' will now be an array with the following content:
Line 85: Line 87:
   
 
==Colors==
 
==Colors==
In above egzamples colors were used in ad explicit names. However, you can specify colors in two ways:
+
In the examples above, colors were used with explicit names. However, colors can be specifiedin 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.
+
*When using the Canon firmware palette as numbers in the range 0-255. These numbers are not portable and the same number migh correspond to other color in an other camera (or even other mode). Also, the same color will have different numerical values for different cameras. Use Canon firmware numbers only to specify tones for a 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:
+
*When using the CHDK script palette. Colors in this palette that are used by drawings module are exactly the same as described in basic Lua drawing commands, except numeric values are not used but names as strings. These names are as follows:
 
Basic colors:
 
Basic colors:
 
trans
 
trans
Line 124: Line 126:
 
 
 
yellow_light
 
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!
+
Basic colors should be available on 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 extended colors are needed in a script, cameras with no color icon 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==
 
==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.
+
It has been stated that when an object is created. it is stored in memory. In fact, all these objects are stored in a two-dimentional array named SCREEN_DRAWINGS. This array can be accessed directly, but use of drawing commands is prefered.
  +
  +
'''NOTE''' : When using the drawing module the name '''SCREEN_DRAWINGS''' cannot be used for any other purposes, due to conflict. The other reserved word is ''draw''. Variable names such as '''''draw''''', '''''draw'''[]'' and other derivatives should not be used
 
[[Category:Lua ]]
 
[[Category:Lua ]]
 
[[Category:Scripting]]
 
[[Category:Scripting]]

Latest revision as of 02:41, November 11, 2013

Drawings - Lua moduleEdit

CHDK 1.2.0 and later  releases  support Lua functions that draw simple shapes on your camera's LCD screen from a script.  See : http://chdk.wikia.com/wiki/Lua/Lua_Reference#Drawings for a description of these functions.

There is also a Lua module that allows you to enhances these drawing functions, giving you more control in adding and removing shapes.  The primary advantage of using this module is that it allows you to easily and simply redraw (repaint) the shapes you have drawn  - something that proves necessary periodically as the Canon UI tends to overwrite things randomly.

These functions are defined in drawings.lua module (A/CHDK/LUALIB/DRAWINGS.LUA).

InitializationEdit

Prior to using the commands listed below, the drawings module has to be initialized with this simple command:

require "drawings"

Note: Do not use .lua extension.

ObjectsEdit

In this manual object is understood as an individual shape with its own parameters, which can be added, removed, moved or changed. Objects that are available through this module are as follows:

Element Element type 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

Parameters in [] are not necessary.

Creating objectsEdit

Before objects can be drawn or seen, they must be created. To create an object use following syntax:

draw.add("element_type", parameter1, parameter2....)

For example, to create an empty rectangle whose top-left corner has the coordinates 10, 50, the bottom-right corner is at 220,200, the color is blue and line thickness is 3 use this command:

draw.add("rect", 10, 50, 220, 200, "blue", 3)

Every time the draw.add() function is called it returns a number which identifies the newly created object. This value can be further used to change various parameters of the object. To obtain this value, use a variable, e.g. my_line_id:

my_line_id=draw.add("line", 45, 30, 100, 101, "red")

Now my_line_id stores the identifier.

Drawing objectsEdit

Once objects have been created,they are stored in memory, but they are not visible on the screen. To draw them use either 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 only the new state visible, whereas draw.overdraw() draws new state but does not remove previous drawings. If an object is moved and then draw.overdraw() is called this object will appear in both places.

Changing objectsEdit

Any previously created objects can be changed with reference to their identifiers. Use this command:

draw.replace(id, "new_element_type", new_param1, new_param2...)

For example, assume a filled rectangle has been created:

my_rect_id=draw.add("rectf", 55, 104, 65, 114, "green", "yellow", 2)

and you would like to move it 30 px to the right, using this coommand:

draw.replace(my_rect_id, "rectf", 85, 104, 95, 114, "green", "yellow", 2)

Note that with draw.replace() every parameter of the object cam be changed. For example the small rectangle from above can be changed into a large circle:

draw.replace(my_rect_id, "elps", 90, 110, 100, 100, "white")

Note also that all these changes will not be visible until draw.redraw() or draw.overdraw() are called.

Removing objectsEdit

A specified object can be removed using:

draw.remove(identifier)

All objects can be remoced by using:

draw.clear()

Note that this command removes objects from the screen as well as from memory. After this command none of these objects will be accessible.

Also note that simple Lua command draw_clear() is used to clear screen and is not the same as draw.clear() from this module!

Retrieving parametersEdit

If the identifier of an object is known then all its parameters can be retrieved as an array. Syntax:

params=draw.get_params(identifier)

For example:

params=draw.get_params(my_rect_id)

Variable params will now be an array with the following content:

{ "elps"​, 90, 110, 100, 100, "white" }

ColorsEdit

In the examples above, colors were used with explicit names. However, colors can be specifiedin two ways:

  • When using the Canon firmware palette as numbers in the range 0-255. These numbers are not portable and the same number migh correspond to other color in an other camera (or even other mode). Also, the same color will have different numerical values for different cameras. Use Canon firmware numbers only to specify tones for a specific camera.
  • When using the CHDK script palette. Colors in this palette that are used by drawings module are exactly the same as described in basic Lua drawing commands, except numeric values are not used but names as strings. 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 on 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 extended colors are needed in a script, cameras with no color icon 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_DRAWINGSEdit

It has been stated that when an object is created. it is stored in memory. In fact, all these objects are stored in a two-dimentional array named SCREEN_DRAWINGS. This array can be accessed directly, but use of drawing commands is prefered.

NOTE : When using the drawing module the name SCREEN_DRAWINGS cannot be used for any other purposes, due to conflict. The other reserved word is draw. Variable names such as draw, draw[] and other derivatives should not be used

Around Wikia's network

Random Wiki