Skip to content

Event handling and 2D graphics for Lua scripts

License

Notifications You must be signed in to change notification settings

TeleMidia/nclua

Repository files navigation

NCLua

The NCLua library adds event handling and 2D graphics to Lua scripts. Programs written in C can use libnclua to run embedded NCLua scripts, i.e., Lua scripts that use the APIs exported by libnclua; Lua scripts can also use libnclua, either through the C API or by requiring the appropriated modules -- e.g., canvas for 2D graphics, event for general event handling, event.stopwatch for stopwatch timers, event.tcp_socket for asynchronous TCP sockets, event.http_soup for asynchronous HTTP requests, etc. The NCLua library comes with a standalone interpreter, called nclua (cf. src/nclua.c), which can be used to run NCLua scripts.

For stable releases and binaries, cf. http://www.telemidia.puc-rio.br/~gflima/nclua.

For the latest sources, cf. https://github.com/telemidia/nclua.

NCLua is the Lua dialect used by the Brazilian digital TV middleware, called Ginga (cf. http://www.ginga.org.br). The reference implementation of Ginga (>= 0.14) uses libnclua to run NCLua scripts.

Building the repository

Dependencies

Required:

Optional:

GIO is used by the tcp event class, Libsoup is used by the http event class, and GTK+ is used by the nclua binary. These libraries are optional, if they are not present the corresponding modules are not built.

Linux

On Ubuntu-based distros, to install the dependencies run:

$ sudo apt-get install -y git gcc g++ autotools-dev dh-autoreconf \
    liblua5.2-dev libglib2.0-dev libpango1.0-dev \
    librsvg2-dev libgtk-3-dev libsoup2.4-dev -qq

To build with autotools run:

$ ./bootstrap
$ ./configure --prefix=/usr/
$ make

Canvas API

For a complete reference, cf. nclua/canvas.c.

Functions:

  • canvas.new creates a new canvas
  • canvas:attrAntiAlias gets or sets the anti-alias attribute
  • canvas:attrClip gets or sets the clip region
  • canvas:attrColor gets or sets the color attribute
  • canvas:attrCrop gets or sets the crop region
  • canvas:attrFilter gets or sets the filter attribute
  • canvas:attrFlip gets or sets the flip attribute
  • canvas:attrFont gets or sets the font attribute
  • canvas:attrLineWidth gets or sets the line width attribute
  • canvas:attrOpacity gets or sets the opacity attribute
  • canvas:attrRotation gets or sets the rotation attribute
  • canvas:attrScale gets or sets the scale attribute
  • canvas:attrSize gets the dimensions in pixels
  • canvas:clear clears canvas
  • canvas:compose composes two canvas
  • canvas:drawEllipse draws an ellipse
  • canvas:drawLine draws a line
  • canvas:drawPolygon draws a polygon
  • canvas:drawRect draws a rectangle
  • canvas:drawRoundRect draws a rectangle with rounded corners
  • canvas:drawText draws text
  • canvas:flush commits the pending operations
  • canvas:measureText measures text
  • canvas:pixel gets or sets pixel

Internal functions (for debugging):

  • canvas:_dump_to_file dumps canvas content to PNG file
  • canvas:_dump_to_memory dumps canvas content to memory address
  • canvas:_resize resizes canvas content
  • canvas:_surface returns a pointer to canvas content

Dir API

For a complete reference, cf. nclua/dir.c.

Functions:

  • dir.dir gets an iterator for path
  • dir.test tests whether path satisfies a given query

Event API

For a complete reference, cf. User API section in nclua/event/init.lua.

Event classes:

  • ncl NCL (Nested Context Language) events
  • key keyboard input
  • pointer mouse input
  • http HTTP requests
  • tcp TCP/IP messages
  • user user defined

Functions:

  • event.post posts event into input or output queues
  • event.register registers event handler
  • event.timer sets up timer that calls a function when expired
  • event.unregister unregisters event handler
  • event.uptime returns the up-time since script started

Libnclua API (C code)

The libnclua API is used by C programs to run NCLua scripts.

Core functions (cf. lib/nclua.c):

  • nclua_open opens the library
  • nclua_close closes the library
  • nclua_cycle processes pending events
  • nclua_receive receives an event
  • nclua_send sends an event
  • nclua_paint paints top-level canvas onto memory
  • nclua_resize resizes top-level canvas

Wrapper functions (cf. lib/ncluaw.c, Lua-free interface):

  • ncluaw_event_key_init initializes key event
  • ncluaw_event_ncl_init initializes NCL event
  • ncluaw_event_pointer_init initializes pointer event
  • ncluaw_event_clone clones event
  • ncluaw_event_free frees event
  • ncluaw_event_equals compares events
  • ncluaw_open opens the wrapper library
  • ncluaw_close closes the wrapper library
  • ncluaw_at_panic installs panic function
  • ncluaw_cycle processes pending events
  • ncluaw_receive receives event
  • ncluaw_send sends event
  • ncluaw_send_key_event sends key event
  • ncluaw_send_ncl_event sends NCL event
  • ncluaw_send_pointer_event sends pointer event
  • ncluaw_paint paints top-level canvas onto memory
  • ncluaw_resize resizes top-level canvas

Copyright (C) 2013-2018 PUC-Rio/Laboratorio TeleMidia

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the "GNU Free Documentation License" file as part of this distribution.