oLv

LÖVE GUI & OSC library modules

oLv is 'omaggio LÖVE'...which means 'Homage to Love'..maybe. Or maybe 'open LÖVE' (I needed an acronym).

Pronounce it 'Oh-Love'...or basically 'Olive'

oLv was written to create easily configurable GUIs for OSC (Open Sound Control) communications between musical effects and synthesizers. Specifically I wrote it to make GUIs for pd2jack in realtime.

oLv uses/depends on the LÖVE 2d game engine, which is flexible, Lua-driven, cross-platform (Mobile! Linux! Etc!) and very easy to use. oLvgui can automatically resize it's interface for mobile devices. It's currently only tested with Linux and Android, however.

• oLvgui was developed in LÖVE V11.3
• oLvosc was developed in LÖVE V11.3 and tested on Lua V5.3

The oLv modules include:

• oLvgui : the GUI
• oLvcolor : color definitions and functions
• oLvext : extras, currently polygon definitions for the GUI

Open Sound Control

oLvosc (pure Lua) & oLvoscT (LÖVE)

oLv includes the olvosc module, a 'pure Lua' library for sending/receiving OSC packets via UDP. There's also a LÖVE-specific module, oLvoscT which is a threaded OSC server

• oLvosc
• oLvoscT

oLvosc modules are included in the oLvgui repositories, but have their own repository.

Thx, D. Garmon

7/2022

Video Demos

• video demo #1 : mkGui & pd2jack, tinaV1

oLv includes these GUI elements:

• Button
• Droplist (can function as a menu)
• Knob
• Label
• Marker (not visible, for gui table manipulations)
• Panel (can function as a graphic element, button, image, x/y 2d input)
• Slider
• Txbox

Also:

• A color theme library
• A library of polygons (used by the Button element, but in std LÖVE format)
• Routines to access GUI data and manipulate the GUI list

The OSC modules include:

• Sending/receiving OSC data packets via UDP
• OSC packet data encoding and decoding
• a LÖVE-only threaded OSC server that can run concurrently with the main thread.

oLv Demos

oLv demo programs, both source and .love files are in these directories in the repository.

• demo_love
• demo_src

Follow this link for simple oLv Demo Documentation. The demo tinaV1 has separate docs, as it depends on Pure Data and a JACK-enabled softsynth.

Any .love files will run under 'LÖVE for Android' app in the Play store. After downloading, they should be launch-able from the Google Files app.

The demo source files are the best documentation, currently...although the info presented below is a start.

GUI Elements

Standard definitions for this section:

• gui_table : a table, a list of all the elements in the current GUI
• label : a string, usually displayed above the element
• {options} : a table of options
• {items} : a table of text entries (for droplists)
• x : x origin of element
• y : y origin of element
• width : width of element
• height : height of element
• value : initial value
• min, max : value limits, min may be negative
• color : color setting, explicit for labels and panels
• presetTx : initial text value
• user : an identifier, but the field can be anything
• callback : is a custom callback function (use same args as the standard callback)

Passing Options

An options table looks like this:

{ 'OPTION1', 'OPTION2'}

Can be defined as a table variable (insert in the creation function):

local myoptions = { 'OPTION1', 'OPTION2'}

GUI Creation functions

Button

oLvgui.createButton(gui_table, label, {options}, x, y, width, height, user (, callback))

Returns a Gui Element

{options} =

• MOMENTARY : immediate mode, callback on buttonDown (default)
• TOGGLE_ON : Toggle value, initially ON, uses polygon image
• TOGGLE_OFF : Toggle value, initially OFF, uses polygon image

Droplist

oLvgui.createDroplist(gui_table, label, {items}, {options}, x, y, width, height, user (, callback))

Returns a Gui Element

{options} =

• DESELECT : value can be NONE (0), no entry or value (default)
• NO_DESELECT : reselecting an item does nothing
• RESEND_SEL : reselecting an item doesn't change item, but does callback
• MENU : A special kind of Droplist, minimal menu functionality

Knob

oLvgui.createKnob(gui_table, label, {options}, x, y, width, height, value, min, max, user (, callback))

Returns a Gui Element

{options} = none

Label

oLvgui.createLabel(gui_table, label, {options}, x, y, width, height, color, user)

Returns a Gui Element

{options} = none

Labels have no callbacks.

Marker

oLvgui.createMarker(gui_table, label, user)

Returns a Gui Element

{options} = none

Markers have no callbacks. They can be embedded in the GUI table, and are used to delete elements before or after the marker.

Panel

oLvgui.createPanel(gui_table, label, {options}, x, y, width, height, color, user (, callback))

Returns a Gui Element

{options} =

• DROPS_ON : dropshadow ON (default)
• DROPS_OFF : dropshadow OFF
• TYPE_NORM : a normal rectangular panel (default)
• TYPE_INTERACT : an interactive panel, functions as a special type of button
• TYPE_IMAGE : a panel with an attached image
• SHOWHIT_ON : displays an x/y touch-mark for an interactive panel
• SHOWHIT_OFF : turn off touch-mark
• FOLLOW_ON : Mouse/touch movements generate callbacks
• FOLLOW_OFF : No callbacks for movement alone

Panels are a swiss-army knife of functions. They act as visual elements, can display pictures, work as interactive buttons and even return the x,y coords of a hit.

Slider

oLvgui.createSlider(gui_table, label, {options}, x, y, width, height, value, min, max, user (, callback))

Returns a Gui Element

{options} =

• HORIZ : Slider is horizontal (default)
• VERT : Slider is vertical
• SHOWV_ON : show label text vertically (default for VERT)
• SHOWV_OFF : show label text horizontially
• RETURN_ON : Slider snaps back to initial value when touch moves outside
• RETURN_OFF : no snap back (default)

Txbox

oLvgui.createTxbox(gui_table, label, {options}, x, y, width, height, presetTx, user (, callback))

Returns a Gui Element

{options} = none

Standard Callbacks

• doButton(state, user)
• doDroplist(index, item_text, user)
• doKnob(value, user)
• doPanel(state, user, x, y)
  • x and y are normalized to a range of 0 - 1
• doSlider(value, user)
• doTxbox(text, user)

Other:

• oLvquit()

See Add a close callback section below.

Using oLv

Load the GUI modules

local oLvgui = require "oLv/oLvgui"
local oLvcolor = require "oLv/oLvcolor"
local oLvext = require "oLv/oLvext"

• "oLvgui.lua" contains the GUI definitions
• "oLvcolor" contains the color and theme defs, etc.
• "oLvext" (extras) contains polygon defs for buttons, etc.

Load the OSC modules

local oLvosc = require "oLv/oLvosc"
local oLvoscT = require "oLv/oLvoscT"

• "oLvosc" contains the standard OSC library, client & server
• "oLvoscT" contains the threaded OSC server

The standard path for the modules is in the /oLv directory within the project dir.

Using the oLvgui module

All the gui functions are accessed with the prefix: oLvgui

For example:

oLvgui.drawoLv(gui)

Note that the oLv module names all have the 'L' char uppercase...

Define a GUI table

Usually just name it 'gui':

local gui = {}

Add a close callback

function oLvquit()
    love.event.quit()
end

While you can close oLv by calling the Std LÖVE function ( love.event.quit() ) anywhere, it's advisable to define this. If this is present, oLv will close correctly when the user hits the Android 'back' button.

This is especially important with the oLv OSC server modules that use threads (olvoscT), as they don't exit gracefully unless the thread is stopped. Especially especially if the platform is Android, as orphaned threads aren't automatically halted.

Here's an example:

function oLvquit()
    local tchn = oLvoscT.getTermChan(chanNm)    -- get the channel to terminate the thread
    oLvoscT.closeServ(tchn)                     -- send a close msg over that channel
    threadT:wait( )                             -- wait for server thread to close...
    love.event.quit()
end

If the threads are not terminated before LÖVE exits, LÖVE may not restart.

Set a color theme and screen size, then Initialize the GUI

In the standard LÖVE 'load' callback:

function love.load()
    local myTheme = oLvgui.createTheme()
    myTheme = oLvcolor.buildColors(oLvcolor.colorT.standard, myTheme)
    oLvgui.initoLv("oLv Demo", 960, 600, myTheme)
    oLvgui.autoScale()

    -- Init the GUI elements here --
end

The function oLvguit.createTheme() creates a basic color theme.

Running that theme through .buildColors() fleshes out the various supporting colors with a VERY simple algorthym. .buildColors() takes a 'quad' of RGB colors (presets and format found in 'oLvcolor.lua') and builds on that.

oLvgui.initoLv() creates a viewPort def, with a Window name, width, height and a theme. The width and height arguments are only valid for desktop use, but they define a working canvas (and w:h ratio) which is very useful when placing GUI elements on the vPort. I.E., don't build a GUI with a w:h of 1920:1080 if the target device is a phone. Even if it's autoscaled (see below) the elements will likely be very small.

The width:height ratio also sets Portrait or Landscape mode on a mobile device.

Mobile devices have a predefined Viewport size. The .autoScale() function will take the current viewPort and GUI and automatically size it to the mobile screen. The function is currently defined for Android only.

Minimally, this should also work:

function love.load()
    local myTheme = oLvgui.createTheme()
    oLvgui.initoLv