Lighting Manipulation

This page provides an overview of the methods available to manipulate the lights on the controller.

-> Module: lightingconsts

-> Object: lightmap

Module: lightingconsts

This object allows for access to various constants used for lighting. Use it to get colours, and lists of colours, and lighting modes.

Getting a colour

Use the object colours to retrieve a colour based on its name. Note that colour names are referred to in all capitals.

The full list of colours is found in lightingconsts.py at approximately line 120.

Example usage:

# Stores the colour red in the variable colour
colour = lightingconsts.colours["RED"]

# Stores the colour lilac into the variable another_colour
another_colour = lightingconsts.colours["LILAC"]

Getting a preset colour

Some functions should be associated with specific colours, and thus have constants associated with them. When possible, use these constants.

The full list of preset colours is available in lightingconsts.py at approximately line 177.

Example usage:

# Stores the colour representing the pencil tool into the variable colour
colour = lightingconsts.TOOL_PENCIL

# Stores the colour representing vertical navigation into the variable another_colour
another_colour = lightingconsts.UI_NAV_VERTICAL

Getting a set of shades of a colour

A selection of colour sets is available. They contain various colours in a particular shade. Later elements in these lists are darker than earlier ones.

Note that only a small number of these are available. If possible, it'd be great if you could add some more.

The full list of colour shade sets is available in lightingconsts.py at approximately line 172.

Example usage:

# Gets a list of blue colours and stores different shades into different variables.
shady_variable = lightingconsts.BLUE_SHADES
colour_1 = shady_variable[0] # Very light blue
colour_2 = shady_variable[4] # Dark blue
colour_3 = shady_variable[2] # Medium blue

Getting a colour from an RGB value

Using lightingconsts.colours.getClosestInt() with an rgb value, returns the colour value for the closest available lighting colour.

Object: LightMap

This object contains information and functions for manipulating the lights on the controller. It is passed to redraw() function in event processor modules.

LightMap.setPadColour(): Set the colour of a drum pad

Arguments:

• x (int): The x coordinate of the drum pad.
• y (int): The y coordinate of the drum pad.
• colour: The colour (gathered using functions in lightingconsts
• state: The lighting mode (see examples). Defaults to normal (lightingconsts.MODE_ON). Can be:
  • MODE_ON: Normal
  • MODE_OFF: Off
  • MODE_PULSE: Pulsing
  • Colour: Flashing with that colour.
• override (bool): Whether to override the current lighting colour and mode. Defaults to False. Don't use this unless you have to.

Example usage:

# Set the top left drum pad to the colour orange.
lights.setPadColour(0, 0, lightingconsts.colous["ORANGE"])

# Set the bottom right drum pad to the colour teal and pulsing.
lights.setPadColour(7, 1, lightingconsts.colous["TEAL"], lightingconsts.MODE_PULSE)

# Set the 5th top drum pad to flash between pink and blue.
lights.setPadColour(4, 0, lightingconsts.colous["PINK"], lightingconsts.colours["BLUE"])

LightMap.setFromMatrix(): Set lights using up to a 9x2 list of lists containing colours

Arguments:

• map: the matrix to set from. Can be up to 9x2 (but should usually be 8x2 so that the circular pads aren't drawn over).
• state: the light mode to set using (or another colour to set as flashing between colours). See above.
• override (bool): whether to override the existing lights. Defaults to False.

Example usage:

# Set every drum pad to purple (since it's the best colour), pulsing and overriding all other lights.
# Create the array
colour_map = [ [ lightingconsts.colours["PURPLE"] ]*2 ]*8
lights.setFromMatrix(colour_map, lightingconsts.MODE_PULSE, True)

Solidifying drum pads

If you haven't drawn on a drum pad, but don't want it to be overwritten by anything, you can solidify it.

LightMap.solidifyPad(): Solidifies a single drum pad

Arguments:

• x: x coordinate
• y: y coordinate

LightMap.solidifyColumn(): Solidifies a column of drum pads

Arguments:

• x: x coordinate

LightMap.solidifyRow(): Solidifies a row of drum pads

Arguments:

• y: y coordinate

LightMap.solidifyAll(): Solidifies all drum pads (excepting circular ones)

It is recommended that you call this function at the end of your redraw functions to prevent other event handlers from drawing after yours.

Adding animations to light drawing

It is possible to add animations to your drawings by using the animation tick. The animation tick value is incremented every redraw cycle and represents the number of ticks since a refresh. Animations can be created using statements such as the following:

# Drawn in first frame
if internal.window.getAnimationTick() >= 0:
   lights.setPadColour(0, 0, lightingconsts.colous["ORANGE"])
# Drawn in second frame
if internal.window.getAnimationTick() >= 1:
   lights.setPadColour(1, 1, lightingconsts.colous["RED"])
   lights.setPadColour(2, 0, lightingconsts.colous["LIME"])
# Etc....

In some cases it may be simpler to use a loop.

# Draw animation on top row.
for i in range(8):
    if i <= internal.window.getAnimationTick():
        lights.setPadColour(i, 0, lightingconsts.colours["RED"])

Resetting the animation tick

If the user performs an action that requires a reset of the animation tick, you can do so with the following function call:

internal.window.resetAnimationTick()