Program Builder

class ledsign.LEDSignProgramBuilder

The LEDSignProgramBuilder class maintains context needed for dynamic program generation. It cannot be created directly; instead it is globally available via LEDSignProgramBuilder.instance() within the stack frames of a decorated LEDSignProgram function (or function called passed to LEDSignProgram.__call__()).

For convenience reasons, all program builder commands are made available in the program function’s global scope, with shorthand aliases for longer ones. The following commands and shortcuts are injected into the global scope:

Command	Shortcut	Builder method
`after()`	`af()`	`command_after()`
`at()`	—	`command_at()`
`cross_fade()`	`cf()`	`command_cross_fade()`
`delta_time()`	`dt()`	`command_delta_time()`
`end()`	—	`command_end()`
`hsv()`	—	`command_hsv()`
`hardware()`	`hw()`	`command_hardware()`
`keypoint()`	`kp()`	`command_keypoint()`
`rgb()`	—	`command_rgb()`
`time()`	`tm()`	`command_time()`

The following example illustrates the three different ways of accessing the keypoint command:

@ledsign.LEDSignProgram(device)
def program():
    at(0)
    keypoint("#ff0000") # <-- alias of the 'keypoint' command
    after(1)
    kp("#00ff00") # <-- shortcut for the 'keypoint' command
    after(1)
    builder=LEDSignProgramBuilder.instance()
    builder.command_keypoint("#0000ff") # <-- underlying 'keypoint' command
    after(1)
    end()

Note

Due to limitations of the internal implementation, these shortcuts can only be accessed by code located within the same file (ie. sharing the same global scope) as the executed program generation function. In other contexts (such as in functions where local closures re-define the command aliases), all commands can be accessed through the current program builder instance, ex. LEDSignProgramBuilder.instance().command_end().

static instance() → LEDSignProgramBuilder | None: Returns the current active instance of LEDSignProgramBuilder, or None if none are active.

command_after(delta_time: int | float) → float: Advances the current timestamp by delta_time (in seconds), and returns its new value. Negative values move back the time, clamping to 0.0 if the resulting timestamp becomes negative.

command_at(time: int | float) → float: Sets the current timestamp to time (in seconds), and returns this new value. Negative values are clamped to 0.0.

command_cross_fade(src: int | str, dst: int | str, t: int | float) → int: Computes the cross-fade (linearly interpolated) between colors src and dst, at time t (normalized between 0.0 and 1.0). Both integer (0xrrggbb) and HTML ("#rrggbb") colors are supported. For other color formats, convert their respective arguments using command_rgb() or command_hsv().

command_delta_time() → float: Returns the interval between consecutive program frames, in seconds.

command_end() → None: Places the program end marker at the current timestamp. All animations after this timestamp will not be compiled. Can be used multiple times to adjust the length of the program.

command_hardware() → LEDSignHardware: Returns the LEDSignHardware object associated with the current program. Can be used as an explicit argument for functions from the LEDSignSelector class (although these functions will call this method internally if no explicit hardware object is supplied to them).

command_hsv(h: int | float, s: int | float, v: int | float) → int: Converts the given (h, s, v) tuple (each element is clamped between 0.0 and 1.0) into a packed 24-bit integer color. Can be used to generate HSV colors for use with the command_keypoint() function.

Creates an rgb-colored keypoint. Both integer (0xrrggbb) and HTML ("#rrggbb") colors are supported. For other color formats, convert their respective arguments using command_rgb() or command_hsv().

If the mask argument is given, only pixels selected by the provided mask will have this keypoint applied to them.

The duration of the animation is specified by the duration argument (in seconds). If left undefined or negative, the animation will be instant.

If the time argument is omitted, the keypoint will terminate at the currently selected timestamp. Otherwise, the keypoint will end at timestamp time, given in seconds.

Warning

During program verification, each keypoint is checked to prevent invalid configurations, usually resulting from bugs in generator code. Two types of invalid keypoint configurations are: (1) negative start time, and (2) ambiguous ordering.

The first error is reported with a keypoint’s start time (ie. its end time minus its duration) predates the start of the program (timestamp 0.0). The compiler is not be able generate the full extent of the animation, and thus the end result is undefined.

The second error occurs when at any point more than one keypoint attempts to apply an animation to the same pixel. Due to undefined compilation ordering, the produced results may not be consistent across compilations.

However, for increased performance, these error-checking functions can be postponed or disabled altogether by setting the bypass_errors flag in relevant LEDSignProgram functions.

command_rgb(r: int | float, g: int | float, b: int | float) → int: Converts the given (r, g, b) tuple (each element is clamped between 0.0 and 1.0) into a packed 24-bit integer color. Can be used to pack individual int or float color channels for use with the command_keypoint() function.

command_time() → float: Returns the current timestamp, in seconds.