diff --git a/.gitignore b/.gitignore index 7f471c4..9208658 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ /build/* /ctruLua.* +/doc/html/* \ No newline at end of file diff --git a/Makefile b/Makefile index e10a175..5451cc2 100644 --- a/Makefile +++ b/Makefile @@ -158,6 +158,9 @@ build-all: @echo Building ctruLua... @make build +build-doc: + @cd doc/ && ldoc . && cd .. + #--------------------------------------------------------------------------------- clean: @rm -fr $(BUILD) $(TARGET).3dsx $(OUTPUT).smdh $(TARGET).elf @@ -186,6 +189,9 @@ clean-all: @echo Cleaning ctruLua... @make clean +clean-doc: + @rm -rf doc/html + #--------------------------------------------------------------------------------- else diff --git a/README.md b/README.md index 47f45c6..b115761 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,8 @@ Warning: the 'u' in the repo's name is a 'µ', not a 'u'. * Clone this repository and run the command `make build-all` to build all the dependencies. * If you only made changes to ctrµLua, run `make` to rebuild ctµLua without rebuilding all the dependencies. +To build the documentation, run `make build-doc` (requires [https://github.com/stevedonovan/LDoc](LDoc)). + May not work under Windows. #### Based on ctrulib by smealum: [https://github.com/smealum/ctrulib](https://github.com/smealum/ctrulib) diff --git a/doc/config.ld b/doc/config.ld new file mode 100644 index 0000000..13c1958 --- /dev/null +++ b/doc/config.ld @@ -0,0 +1,26 @@ +-- General options +title = "ctrµLua documentation" +project = "ctrµLua" +description = "ctrµLua: Lua homebrewing for 3DS" +not_luadoc = true + +-- Generation options +dir = "./html/" +style = "!fixed" +format = "markdown" +plain = true + +-- Input files +topics = "../README.md" +file = "../source/" +examples = "../sdcard/3ds/ctruLua/examples/" +manual_url = "file://../libs/lua-5.3.1/doc/manual.html" + +-- Custom tags +custom_tags = { { "newonly", hidden = true } } +custom_display_name_handler = function(item, default_handler) + if item.tags.newonly then + return default_handler(item).." (N3DS only)" + end + return default_handler(item) +end diff --git a/doc/newonly.png b/doc/newonly.png new file mode 100644 index 0000000..35ab169 Binary files /dev/null and b/doc/newonly.png differ diff --git a/sdcard/3ds/ctruLua/example.lua b/sdcard/3ds/ctruLua/examples/example.lua similarity index 100% rename from sdcard/3ds/ctruLua/example.lua rename to sdcard/3ds/ctruLua/examples/example.lua diff --git a/source/ctr.c b/source/ctr.c index 0fe153e..37e2c19 100644 --- a/source/ctr.c +++ b/source/ctr.c @@ -1,3 +1,8 @@ +/*** +The `ctr` module. +@module ctr +@usage local ctr = require("ctr") +*/ #include <3ds/types.h> #include <3ds/services/apt.h> #include <3ds/os.h> @@ -5,27 +10,84 @@ #include #include +/*** +The `ctr.gfx` module. +@table gfx +@see ctr.gfx +*/ void load_gfx_lib(lua_State *L); -void load_news_lib(lua_State *L); -void load_ptm_lib(lua_State *L); -void load_hid_lib(lua_State *L); -void load_ir_lib(lua_State *L); -void load_fs_lib(lua_State *L); -void load_httpc_lib(lua_State *L); -void load_qtm_lib(lua_State *L); -//void load_cam_lib(lua_State *L); - void unload_gfx_lib(lua_State *L); + +/*** +The `ctr.news` module. +@table news +@see ctr.news +*/ +void load_news_lib(lua_State *L); + +/*** +The `ctr.ptm` module. +@table ptm +@see ctr.ptm +*/ +void load_ptm_lib(lua_State *L); + +/*** +The `ctr.hid` module. +@table hid +@see ctr.hid +*/ +void load_hid_lib(lua_State *L); void unload_hid_lib(lua_State *L); + +/*** +The `ctr.ir` module. +@table ir +@see ctr.ir +*/ +void load_ir_lib(lua_State *L); + +/*** +The `ctr.fs` module. +@table fs +@see ctr.fs +*/ +void load_fs_lib(lua_State *L); void unload_fs_lib(lua_State *L); + +/*** +The `ctr.httpc` module. +@table httpc +@see ctr.httpc +*/ +void load_httpc_lib(lua_State *L); void unload_httpc_lib(lua_State *L); +/*** +The `ctr.qtm` module. +@table qtm +@see ctr.qtm +*/ +void load_qtm_lib(lua_State *L); + +//void load_cam_lib(lua_State *L); + +/*** +Return whether or not the program should continue. +@function run +@treturn boolean `false` if the program should exist or `true` if it can continue +*/ static int ctr_run(lua_State *L) { lua_pushboolean(L, aptMainLoop()); return 1; } +/*** +Return the number of milliseconds since 1st Jan 1900 00:00. +@function time +@treturn number milliseconds +*/ static int ctr_time(lua_State *L) { lua_pushinteger(L, osGetTime()); diff --git a/source/gfx.c b/source/gfx.c index 4dc4248..f070648 100644 --- a/source/gfx.c +++ b/source/gfx.c @@ -1,3 +1,8 @@ +/*** +The `gfx` module. +@module ctr.gfx +@usage local gfx = require("ctr.gfx") +*/ #include #include @@ -12,15 +17,43 @@ bool isGfxInitialised = false; +/*** +The `ctr.gfx.color` module. +@table color +@see ctr.gfx.color +*/ void load_color_lib(lua_State *L); -void load_font_lib(lua_State *L); -void load_texture_lib(lua_State *L); -void load_map_lib(lua_State *L); - -void unload_font_lib(lua_State *L); - u32 color_default; +/*** +The `ctr.gfx.font` module. +@table font +@see ctr.gfx.font +*/ +void load_font_lib(lua_State *L); +void unload_font_lib(lua_State *L); + +/*** +The `ctr.gfx.texture` module. +@table texture +@see ctr.gfx.texture +*/ +void load_texture_lib(lua_State *L); + +/*** +The `ctr.gfx.map` module. +@table map +@see ctr.gfx.map +*/ +void load_map_lib(lua_State *L); + +/*** +Start drawing to a screen. +Must be called before any draw operation. +@function startFrame +@tparam number screen the screen to draw to (`GFX_TOP` or `GFX_BOTTOM`) +@tparam[opt=GFX_LEFT] number eye the eye to draw to (`GFX_LEFT` or `GFX_RIGHT`) +*/ static int gfx_startFrame(lua_State *L) { u8 screen = luaL_checkinteger(L, 1); u8 eye = luaL_optinteger(L, 2, GFX_LEFT); @@ -30,18 +63,32 @@ static int gfx_startFrame(lua_State *L) { return 0; } +/*** +End drawing to a screen. +Must be called after your draw operations. +@function endFrame +*/ static int gfx_endFrame(lua_State *L) { sf2d_end_frame(); return 0; } +/*** +Display any drawn pixel. +@function render +*/ static int gfx_render(lua_State *L) { sf2d_swapbuffers(); return 0; } +/*** +Get the current number of frame per second. +@function getFPS +@treturn number number of frame per seconds +*/ static int gfx_getFPS(lua_State *L) { float fps = sf2d_get_fps(); @@ -50,6 +97,11 @@ static int gfx_getFPS(lua_State *L) { return 1; } +/*** +Enable or disable the stereoscopic 3D on the top screen. +@function set3D +@tparam boolean enable true to enable, false to disable +*/ static int gfx_set3D(lua_State *L) { bool enable = lua_toboolean(L, 1); @@ -58,12 +110,26 @@ static int gfx_set3D(lua_State *L) { return 0; } +/*** +Get free VRAM space. +@function vramSpaceFree +@treturn integer free VRAM in bytes +*/ static int gfx_vramSpaceFree(lua_State *L) { lua_pushinteger(L, vramSpaceFree()); return 1; } +/*** +Draw a line on the current screen. +@function line +@tparam integer x1 line's starting point horizontal coordinate, in pixels +@tparam integer y1 line's starting point vertical coordinate, in pixels +@tparam integer x2 line's endpoint horizontal coordinate, in pixels +@tparam integer y2 line's endpoint vertical coordinate, in pixels +@tparam[opt=default color] integer color drawing color +*/ static int gfx_line(lua_State *L) { int x1 = luaL_checkinteger(L, 1); int y1 = luaL_checkinteger(L, 2); @@ -77,6 +143,13 @@ static int gfx_line(lua_State *L) { return 0; } +/*** +Draw a point, a single pixel, on the current screen. +@function point +@tparam integer x point horizontal coordinate, in pixels +@tparam integer y point vertical coordinate, in pixels +@tparam[opt=default color] integer color drawing color +*/ static int gfx_point(lua_State *L) { int x = luaL_checkinteger(L, 1); int y = luaL_checkinteger(L, 2); @@ -88,6 +161,16 @@ static int gfx_point(lua_State *L) { return 0; } +/*** +Draw a rectangle on the current screen. +@function rectangle +@tparam integer x rectangle origin horizontal coordinate, in pixels +@tparam integer y rectangle origin vertical coordinate, in pixels +@tparam integer width rectangle width, in pixels +@tparam integer height rectangle height, in pixels +@tparam[opt=0] number angle rectangle rotation, in radians +@tparam[opt=default color] integer color drawing color +*/ static int gfx_rectangle(lua_State *L) { int x = luaL_checkinteger(L, 1); int y = luaL_checkinteger(L, 2); @@ -105,6 +188,14 @@ static int gfx_rectangle(lua_State *L) { return 0; } +/*** +Draw a circle on the current screen. +@function circle +@tparam integer x circle center horizontal coordinate, in pixels +@tparam integer y circle center vertical coordinate, in pixels +@tparam integer radius circle radius, in pixels +@tparam[opt=default color] integer color drawing color +*/ static int gfx_circle(lua_State *L) { int x = luaL_checkinteger(L, 1); int y = luaL_checkinteger(L, 2); @@ -117,6 +208,16 @@ static int gfx_circle(lua_State *L) { return 0; } +/*** +Draw a text on the current screen. +@function text +@tparam integer x text drawing origin horizontal coordinate, in pixels +@tparam integer y text drawing origin vertical coordinate, in pixels +@tparam string text the text to draw +@tparam[opt=9] integer size drawing size, in pixels +@tparam[opt=default color] integer color drawing color +@tparam[opt=default font] font font to use +*/ static int gfx_text(lua_State *L) { int x = luaL_checkinteger(L, 1); int y = luaL_checkinteger(L, 2); @@ -161,13 +262,53 @@ static const struct luaL_Reg gfx_lib[] = { // Constants struct { char *name; int value; } gfx_constants[] = { + /*** + Constant used to select the top screen. + It is equal to `0`. + @field GFX_TOP + */ { "GFX_TOP", GFX_TOP }, + /*** + Constant used to select the bottom screen. + It is equal to `1`. + @field GFX_BOTTOM + */ { "GFX_BOTTOM", GFX_BOTTOM }, + /*** + Constant used to select the left eye. + It is equal to `0`. + @field GFX_LEFT + */ { "GFX_LEFT", GFX_LEFT }, + /*** + Constant used to select the right eye. + It is equal to `1`. + @field GFX_RIGHT + */ { "GFX_RIGHT", GFX_RIGHT }, + /*** + The top screen height, in pixels. + It is equal to `240`. + @field TOP_HEIGHT + */ { "TOP_HEIGHT", 240 }, + /*** + The top screen width, in pixels. + It is equal to `400`. + @field TOP_WIDTH + */ { "TOP_WIDTH", 400 }, + /*** + The bottom screen height, in pixels. + It is equal to `240`. + @field BOTTOM_HEIGHT + */ { "BOTTOM_HEIGHT", 240 }, + /*** + The bottom screen width, in pixels. + It is equal to `320`. + @field BOTTOM_WIDTH + */ { "BOTTOM_WIDTH", 320 }, { NULL, 0 } };