Commit d256fdf3 authored by David Milligan's avatar David Milligan
Browse files

lua.mo: move documentation into comments, use luadoc format (convert to html with ldoc)

ldoc: http://stevedonovan.github.io/ldoc/

--HG--
branch : lua
parent e19b90ae3bd0
......@@ -43,8 +43,8 @@ static int lua_loaded = 0;
int lua_running = 0;
int last_keypress = 0;
/**
* Determines if a string ends in some string
/*
Determines if a string ends in some string
*/
static int string_ends_with(const char *source, const char *ending)
{
......@@ -54,6 +54,20 @@ static int string_ends_with(const char *source, const char *ending)
return !strcmp(source + strlen(source) - strlen(ending), ending);
}
/***
Global Functions
@author Magic Lantern Team
@copyright 2014
@license GPL
@module global
*/
/***
Beep
@tparam[opt=1] integer times number of times to beep
@function beep
*/
static int luaCB_beep(lua_State * L)
{
LUA_PARAM_INT_OPTIONAL(times, 1, 1);
......@@ -61,6 +75,13 @@ static int luaCB_beep(lua_State * L)
return 0;
}
/***
Calls an eventproc (a function from the camera firmware which can be called by name).
See Eventprocs. Dangerous.
@tparam string function the name of the function to call
@param[opt=1] arg argument to pass to the call
@function call
*/
static int luaCB_call(lua_State * L)
{
LUA_PARAM_STRING(function_name, 1);
......@@ -91,6 +112,12 @@ static int luaCB_call(lua_State * L)
return 1;
}
/***
Take a picture
@tparam[opt=64] integer wait how long to wait for camera to be ready to take a picture
@tparam[opt=true] boolean should_af whether ot not to us auto focus
@function shoot
*/
static int luaCB_shoot(lua_State * L)
{
LUA_PARAM_INT_OPTIONAL(wait, 1, 64);
......@@ -100,6 +127,11 @@ static int luaCB_shoot(lua_State * L)
return 1;
}
/***
Pauses for ms miliseconds and allows other tasks to run.
@tparam integer amount number of milliseconds to sleep
@function msleep
*/
static int luaCB_msleep(lua_State * L)
{
LUA_PARAM_INT(amount, 1);
......
/***
Basic camera operations and properties
@author Magic Lantern Team
@copyright 2014
@license GPL
@module camera
*/
#include <dryos.h>
#include <string.h>
......@@ -9,19 +17,47 @@
static int luaCB_camera_index(lua_State * L)
{
LUA_PARAM_STRING_OPTIONAL(key, 2, "");
/// Shutter shutter speed in apex units x10
// @tfield integer shutter
if(!strcmp(key, "shutter")) lua_pushinteger(L, RAW2TV(lens_info.raw_shutter));
/// Lens aperture in apex units x10
// @tfield integer aperture
else if(!strcmp(key, "aperture")) lua_pushinteger(L, RAW2AV(lens_info.raw_aperture));
/// ISO in apex units x10
// @tfield integer iso
else if(!strcmp(key, "iso")) lua_pushinteger(L, RAW2SV(lens_info.raw_iso));
/// Exposure compensation in apex units x10
// @tfield integer ec
else if(!strcmp(key, "ec")) lua_pushinteger(L, RAW2EC(lens_info.ae));
/// Flash exposure compensation in apex units x10
// @tfield integer flash_ec
else if(!strcmp(key, "flash_ec")) lua_pushinteger(L, RAW2EC(lens_info.flash_ae));
/// The current camera mode, possible values defined in MODE global
// @tfield integer mode
else if(!strcmp(key, "mode")) lua_pushinteger(L, shooting_mode);
/// The current auto focus mode
// @tfield integer af_mode readonly
else if(!strcmp(key, "af_mode")) lua_pushinteger(L, af_mode);
/// The current metering mode
// @tfield integer metering_mode readonly
else if(!strcmp(key, "metering_mode")) lua_pushinteger(L, metering_mode);
/// The current drive mode
// @tfield integer drive_mode readonly
else if(!strcmp(key, "drive_mode")) lua_pushinteger(L, drive_mode);
/// The model name of the camera
// @tfield string model readonly
else if(!strcmp(key, "model")) lua_pushstring(L, camera_model);
/// The shortened model name of the camera (e.g. 5D3)
// @tfield string model_short readonly
else if(!strcmp(key, "model_short")) lua_pushstring(L, __camera_model_short);
/// The Canon firmware version string
// @tfield string firmware readonly
else if(!strcmp(key, "firmware")) lua_pushstring(L, firmware_version);
/// The temperature from the efic chip in raw units
// @tfield integer temperature readonly
else if(!strcmp(key, "temperature")) lua_pushinteger(L, efic_temp);
/// The current Canon GUI state of the camera (PLAY, QR, LV, etc)
// @tfield integer state readonly
else if(!strcmp(key, "state")) lua_pushinteger(L, gui_state);
else lua_rawget(L, 1);
return 1;
......@@ -66,6 +102,12 @@ static int luaCB_camera_newindex(lua_State * L)
return 0;
}
/***
Take a picture
@tparam[opt=64] integer wait how long to wait for camera to be ready to take a picture
@tparam[opt=true] boolean should_af whether ot not to us auto focus
@function shoot
*/
static int luaCB_camera_shoot(lua_State * L)
{
LUA_PARAM_INT_OPTIONAL(wait, 1, 64);
......@@ -75,6 +117,11 @@ static int luaCB_camera_shoot(lua_State * L)
return 1;
}
/***
Take a picture in bulb mode
@tparam integer duration bulb duration in seconds
@function bulb
*/
static int luaCB_camera_bulb(lua_State * L)
{
LUA_PARAM_INT(duration, 1);
......
/***
Functions for writing data to the console
@author Magic Lantern Team
@copyright 2014
@license GPL
@module console
*/
#include <dryos.h>
#include <string.h>
#include <console.h>
#include "lua_common.h"
/***
Show the console
@function show
*/
static int luaCB_console_show(lua_State * L)
{
console_show();
return 0;
}
/***
Hide the console
@function hide
*/
static int luaCB_console_hide(lua_State * L)
{
console_hide();
return 0;
}
/***
Write some text to the console
@tparam string text the text to write
@function write
*/
static int luaCB_console_write(lua_State * L)
{
if(lua_isstring(L, 1)) console_puts(lua_tostring(L, 1));
......
/***
Display and bmp drawing functions functions
@author Magic Lantern Team
@copyright 2014
@license GPL
@module display
*/
#include <dryos.h>
#include <string.h>
......@@ -8,18 +16,32 @@
#include "lua_common.h"
/***
Turn the display on
@function on
*/
static int luaCB_display_on(lua_State * L)
{
display_on();
return 0;
}
/***
Turn the display off
@function off
*/
static int luaCB_display_off(lua_State * L)
{
display_off();
return 0;
}
/***
Take a screenshot
@tparam[opt] string filename
@tparam[opt] integer mode
@function screenshot
*/
static int luaCB_display_screenshot(lua_State * L)
{
LUA_PARAM_STRING_OPTIONAL(filename, 1, SCREENSHOT_FILENAME_AUTO);
......@@ -28,12 +50,26 @@ static int luaCB_display_screenshot(lua_State * L)
return 0;
}
/***
Clear the screen
@function clear
*/
static int luaCB_display_clear(lua_State * L)
{
clrscr();
return 0;
}
/***
Print text to the screen.
@tparam string text
@tparam integer x
@tparam integer y
@tparam[opt] integer font
@tparam[opt] integer fg foreground color
@tparam[opt] integer bg background color
@function print
*/
static int luaCB_display_print(lua_State * L)
{
LUA_PARAM_STRING(str, 1);
......@@ -46,6 +82,13 @@ static int luaCB_display_print(lua_State * L)
return 0;
}
/***
Set a pixel to a color
@tparam integer x
@tparam integer y
@tparam integer color
@function pixel
*/
static int luaCB_display_pixel(lua_State * L)
{
LUA_PARAM_INT(x, 1);
......@@ -55,6 +98,15 @@ static int luaCB_display_pixel(lua_State * L)
return 0;
}
/***
Set a pixel to a color
@tparam integer x1
@tparam integer y1
@tparam integer x2
@tparam integer y2
@tparam integer color
@function pixel
*/
static int luaCB_display_line(lua_State * L)
{
LUA_PARAM_INT(x1, 1);
......@@ -66,6 +118,16 @@ static int luaCB_display_line(lua_State * L)
return 0;
}
/***
Set a pixel to a color
@tparam integer x
@tparam integer y
@tparam integer w
@tparam integer h
@tparam integer stroke outline color
@tparam[opt] integer fill fill color
@function pixel
*/
static int luaCB_display_rect(lua_State * L)
{
LUA_PARAM_INT(x, 1);
......@@ -79,6 +141,15 @@ static int luaCB_display_rect(lua_State * L)
return 0;
}
/***
Draw a circle
@tparam integer x center x
@tparam integer y center y
@tparam integer r radius
@tparam integer stroke outline color
@tparam[opt] integer fill fill color
@function pixel
*/
static int luaCB_display_circle(lua_State * L)
{
LUA_PARAM_INT(x, 1);
......
/***
Key functions
@author Magic Lantern Team
@copyright 2014
@license GPL
@module key
*/
#include <dryos.h>
#include <string.h>
......@@ -7,6 +15,11 @@
extern int last_keypress;
int module_send_keypress(int module_key);
/***
Send a keypress.
@tparam integer key the key to press
@function press
*/
static int luaCB_key_press(lua_State * L)
{
LUA_PARAM_INT(key, 1);
......@@ -14,6 +27,13 @@ static int luaCB_key_press(lua_State * L)
return 0;
}
/***
Wait for a key to be pressed.
@tparam[opt] integer key
@tparam[opt] integer timeout
@return the key that was pressed
@function wait
*/
static int luaCB_key_wait(lua_State * L)
{
LUA_PARAM_INT_OPTIONAL(key, 1, 0);
......@@ -38,6 +58,8 @@ static int luaCB_key_wait(lua_State * L)
static int luaCB_key_index(lua_State * L)
{
LUA_PARAM_STRING_OPTIONAL(key, 2, "");
/// The last key that was pressed.
// @tfield integer last
if(!strcmp(key, "last")) lua_pushinteger(L, last_keypress);
else lua_rawget(L, 1);
return 1;
......
/***
Lens functions
@author Magic Lantern Team
@copyright 2014
@license GPL
@module lens
*/
#include <dryos.h>
#include <string.h>
......@@ -9,12 +17,26 @@
static int luaCB_lens_index(lua_State * L)
{
LUA_PARAM_STRING_OPTIONAL(key, 2, "");
/// The name of the lens (reported by the lens)
// @tfield string name readonly
if(!strcmp(key, "name")) lua_pushstring(L, lens_info.name);
/// The focal length of the lens (in mm)
// @tfield integer focal_length readonly
else if(!strcmp(key, "focal_length")) lua_pushinteger(L, lens_info.focal_len);
/// The current focal distance (in cm)
// @tfield integer focal_distance readonly
else if(!strcmp(key, "focal_distance")) lua_pushinteger(L, lens_info.focus_dist);
/// The hyperfocal distance of the lens (in mm)
// @tfield integer hyperfocal readonly
else if(!strcmp(key, "hyperfocal")) lua_pushinteger(L, lens_info.hyperfocal);
/// The distance to the DOF near (in mm)
// @tfield integer dof_near readonly
else if(!strcmp(key, "dof_near")) lua_pushinteger(L, lens_info.dof_near);
/// The distance to the DOF far (in mm)
// @tfield integer dof_far readonly
else if(!strcmp(key, "dof_far")) lua_pushinteger(L, lens_info.dof_far);
/// Whether or not auto focus is enabled
// @tfield boolean af readonly
else if(!strcmp(key, "af")) lua_pushboolean(L, !is_manual_focus());
else lua_rawget(L, 1);
return 1;
......@@ -34,6 +56,14 @@ static int luaCB_lens_newindex(lua_State * L)
return 0;
}
/***
Moves the focus motor a specified number of steps. Only works in LV.
@tparam integer num_steps
@tparam[opt=1] integer step_size
@tparam[opt=1] integer wait
@tparam[opt=0] integer extra_delay
@function focus
*/
static int luaCB_lens_focus(lua_State * L)
{
LUA_PARAM_INT(num_steps, 1);
......
/***
LiveView functions
@author Magic Lantern Team
@copyright 2014
@license GPL
@module lv
*/
#include <dryos.h>
#include <string.h>
......@@ -10,6 +18,8 @@
static int luaCB_lv_index(lua_State * L)
{
LUA_PARAM_STRING_OPTIONAL(key, 2, "");
/// Whether or not LV is running.
// @tfield boolean enabled
if(!strcmp(key, "enabled")) lua_pushboolean(L, lv);
else lua_rawget(L, 1);
return 1;
......@@ -31,24 +41,40 @@ static int luaCB_lv_newindex(lua_State * L)
return 0;
}
/***
Enter LiveView.
@function start
*/
static int luaCB_lv_start(lua_State * L)
{
force_liveview();
return 0;
}
/***
Pause LiveView (but leave shutter open).
@function pause
*/
static int luaCB_lv_pause(lua_State * L)
{
PauseLiveView();
return 0;
}
/***
Resume LiveView.
@function resume
*/
static int luaCB_lv_resume(lua_State * L)
{
ResumeLiveView();
return 0;
}
/***
Exit LiveView.
@function stop
*/
static int luaCB_lv_stop(lua_State * L)
{
close_liveview();
......
/***
Functions for interacting with the ML menu
@author Magic Lantern Team
@copyright 2014
@license GPL
@module menu
*/
#include <dryos.h>
#include <string.h>
......@@ -157,6 +165,42 @@ static int get_index_for_choices(struct menu_entry * menu_entry, const char * va
return 0;
}
/// Creates a new menu item
// @tparam table definition
// @function new
// @return a menu object
static int luaCB_menu_new(lua_State * L)
{
if(!lua_istable(L, 1)) return luaL_argerror(L, 1, "expected table");
lua_pushvalue(L, 1);
const char * parent = LUA_FIELD_STRING("parent", "LUA");
lua_pop(L, 1);
struct script_menu_entry * new_entry = lua_newuserdata(L, sizeof(struct script_menu_entry));
//add a metatable to the userdata object for value lookups and to store submenu
lua_newtable(L);
lua_pushcfunction(L, luaCB_menu_index);
lua_setfield(L, -2, "__index");
lua_pushcfunction(L, luaCB_menu_newindex);
lua_setfield(L, -2, "__newindex");
lua_pushcfunction(L, luaCB_menu_remove);
lua_setfield(L, -2, "remove");
lua_pushstring(L, parent);
lua_setfield(L, -2, "parent");
lua_setmetatable(L, -2);
lua_pushvalue(L, 1);
load_menu_entry(L, new_entry, NULL, "unknown");
menu_add(parent, new_entry->menu_entry, 1);
lua_pop(L, 1);
return 1; //return the userdata object
}
/// Represents a menu item
// @type menu
static int luaCB_menu_index(lua_State * L)
{
if(!lua_isuserdata(L, 1)) return luaL_argerror(L, 1, NULL);
......@@ -164,6 +208,8 @@ static int luaCB_menu_index(lua_State * L)
if(!script_entry || !script_entry->menu_entry) return luaL_argerror(L, 1, "internal error: userdata was NULL");
LUA_PARAM_STRING_OPTIONAL(key, 2, "");
/// current value of the menu item
// @tfield integer value
if(!strcmp(key, "value"))
{
if(script_entry->menu_entry->choices)
......@@ -175,27 +221,76 @@ static int luaCB_menu_index(lua_State * L)
lua_pushinteger(L, script_entry->menu_value);
}
}
/// Name for the menu item
// @tfield string name
else if(!strcmp(key, "name")) lua_pushstring(L, script_entry->menu_entry->name);
/// Help text for the menu item (line 1)
// @tfield string help
else if(!strcmp(key, "help")) lua_pushstring(L, script_entry->menu_entry->help);
/// Help text for the menu item (line 2)
// @tfield string help2
else if(!strcmp(key, "help2")) lua_pushstring(L, script_entry->menu_entry->help2);
/// Advanced setting in submenus; add a MENU_ADVANCED_TOGGLE if you use it
// @tfield boolean advanced
else if(!strcmp(key, "advanced")) lua_pushinteger(L, script_entry->menu_entry->advanced);
/// Dependencies for this menu item. Possible values are specified in the 'DEPENDS_ON' global.
// If the dependecies are not met, the item will be greyed out and a warning will appear at the bottom of the screen.
// @tfield integer depends_on
else if(!strcmp(key, "depends_on")) lua_pushinteger(L, script_entry->menu_entry->depends_on);
/// Editing mode for the menu item
// @tfield integer edit_mode
else if(!strcmp(key, "edit_mode")) lua_pushinteger(L, script_entry->menu_entry->edit_mode);
/// Hidden from main menu
// @tfield integer hidden
else if(!strcmp(key, "hidden")) lua_pushinteger(L, script_entry->menu_entry->hidden);
/// The type of icon to use for this menu item. Possible values are specified in the 'ICON_TYPE' global
// @tfield integer icon_type
else if(!strcmp(key, "icon_type")) lua_pushinteger(L, script_entry->menu_entry->icon_type);
else if(!strcmp(key, "jhidden")) lua_pushinteger(L, script_entry->menu_entry->jhidden);
/// Hidden from junkie menu
// @tfield boolean jhidden
else if(!strcmp(key, "jhidden")) lua_pushboolean(L, script_entry->menu_entry->jhidden);
/// The maximum value the menu item can have
// @tfield integer max
else if(!strcmp(key, "max")) lua_pushinteger(L, script_entry->menu_entry->max);
/// The minimum value the menu item can have
// @tfield integer min
else if(!strcmp(key, "min")) lua_pushinteger(L, script_entry->menu_entry->min);
else if(!strcmp(key, "selected")) lua_pushinteger(L, script_entry->menu_entry->selected);
else if(!strcmp(key, "shidden")) lua_pushinteger(L, script_entry->menu_entry->shidden);
else if(!strcmp(key, "starred")) lua_pushinteger(L, script_entry->menu_entry->starred);
/// Whether or not the menu is selected
// @tfield integer selected
else if(!strcmp(key, "selected")) lua_pushboolean(L, script_entry->menu_entry->selected);
/// Special hide, not toggleable by user
// @tfield boolean shidden
else if(!strcmp(key, "shidden")) lua_pushboolean(L, script_entry->menu_entry->shidden);
/// Present in "my menu"
// @tfield boolean starred
else if(!strcmp(key, "starred")) lua_pushboolean(L, script_entry->menu_entry->starred);
/// Submenu Height
// @tfield integer submenu_height
else if(!strcmp(key, "submenu_height")) lua_pushinteger(L, script_entry->menu_entry->submenu_height);
/// Submenu Width
// @tfield integer submenu_width
else if(!strcmp(key, "submenu_width")) lua_pushinteger(L, script_entry->menu_entry->submenu_width);
/// The unit for the menu item's value. Possible values are specified in the 'UNIT' global
// @tfield integer unit
else if(!strcmp(key, "unit")) lua_pushinteger(L, script_entry->menu_entry->unit);
/// Suggested operating mode for this menu item. Possible values are specified in the "WORKS_BEST_IN' global.
// @tfield integer works_best_in
else if(!strcmp(key, "works_best_in")) lua_pushinteger(L, script_entry->menu_entry->works_best_in);
/// Function called when menu is toggled
// @tparam integer delta
// @function select
else if(!strcmp(key, "select")) lua_rawgeti(L, LUA_REGISTRYINDEX, script_entry->select_ref);
/// Function called when menu is displayed. Return a string to be displayed.
// @return string
// @function update
else if(!strcmp(key, "update")) lua_rawgeti(L, LUA_REGISTRYINDEX, script_entry->update_ref);
/// Function called when menu is displayed. Return a string to be displayed in the info area (in green).
// @return string
// @function info
else if(!strcmp(key, "info")) lua_rawgeti(L, LUA_REGISTRYINDEX, script_entry->info_ref);
/// Function called when menu is displayed. Return a string when there is a warning (menu will be greyed out).
// @return string
// @function select
else if(!strcmp(key, "warning")) lua_rawgeti(L, LUA_REGISTRYINDEX, script_entry->warning_ref);
else
{
......@@ -354,6 +449,8 @@ static void load_menu_entry(lua_State * L, struct script_menu_entry * script_ent
menu_entry->jhidden = LUA_FIELD_INT("jhidden", 0);