Introduction

Lucinate is a modular layer-based app for algorithmic art, generative visuals, video synthesis, and image processing.

It comes with a bunch of ready-made shader libraries to get you started right away, as well as built-in library functions to aid you in coding your own shaders.

Strips

The main view shows a number of columns, called Strips. Each strip contains an Output View, a Toolbar, and a Shader Stack.

Tap the plus button to add a new strip.

Output View

At the top of each Strip is the shader output view, which displays the currently generated video output from the shader stack of this strip.

Shader Stack

Below the output view and toolbar is the most important thing, the Shader Stack, which is a stack of Shader Layers, where each layer runs a Shader Function. The image travels bottom-up, from background to foreground.

The stack starts empty. Tap the big Background button to add a new Shader Layer.

The bottom of the stack also holds Modulators, that can modulate any parameters of Shader Layers or Modulator Layers. Tap the big Modulator button to add a new Modulator.

Between the output view and shader stack is a toolbar with various controls:

Stack Menu: Show a menu with actions and settings for this stack.
Play: Toggle play for this stack. When playing, the output view is rendered each frame and time is incremented.
Rewind: Restart all shaders in this stack from time 0. Long-press or Cmd-click to reset touch/move/cam uniforms.
Preview Mode: Change the Preview Mode.
Expand: Expand the output view, keeping the strip as a side-bar. (Not available on iPhone)
Fullscreen: Show output view in fullscreen. On iPhone, you can also rotate the phone to landscape orientation to automatically go fullscreen.
Display: Select this stack as Main Output to be sent to video recording and external display. Deselect it to black out the display window.

You can re-order strips by dragging the toolbar and dropping it before or after another strip.

Preview Modes

Opaque: Draw the output view opaque, ignoring the alpha channel.
Alpha Blend: Blends the output view against a background. The background color and pattern is set in the preview settings.
Inspect RGBA: Inspect the RGBA color components. Draws each component in its own quarter. Tap and drag the screen to zoom and show pixel value. Infinite values are shown in cyan, NaNs in magenta, negative values in orange, and values above 1.0 in yellow.
Pixel Zoom: Inspect pixels. Tap and drag the screen to move the zoom-window.

Stack Settings

Trash

Delete this strip.

Export Snapshot

Export the current frame as an image: PNG, HEIC, HEIC HDR, JPEG, or Copy to Pasteboard.

More...

Add Strip Before
Add Strip After
Copy
Paste
Duplicate
Remove all Layers
Remove disabled Layers

Render Target

Resolution: Tap to set custom fixed resolution.
Scale factor: Follow project resolution by scale factor.
Mipmapped: Enable mipmap generation.

Framerate

Divider: Divide the frame rate.

Controls

touch value.
move value.
cam.org value.
cam.dir value.
cam.orbit value.
Reset.

Shader Layer

The Shader Layer contains a Shader Function, which is the small GPU-program that generates or processes the actual image, all the controls and inputs of the shader function, and an optional blend operation.

Buttons

A layer consists of the following elements:

Expand: Expands or collapses the various controls and inputs for this layer. Long-press or Cmd-click to expand/collapse this and all layers below.
Function: Shows the Library Browser that allows you to select and load a Shader Function.
Blend: Shows the blending-options for this layer.
Visible: Toggles this layer on or off. Long-press or Cmd-click to solo this layer, temporarily disabling all layers above it.

Long-press (iOS) or right-click (Mac) the Function button to show a menu of actions for this layer:

Edit Code: Open this function in the code editor.
Insert Above: Insert a new layer above this layer.
Insert Below: Insert a new layer below this layer.
Reset Parameters: Reset all parameters to default values.
Copy: Copy to clipboard.
Paste: Paste from clipboard.
Duplicate: Duplicate this layer.
Remove: Delete this layer.

You can re-order layers and move them between stacks by drag-and-drop.

Library Browser

A Library is a text file containing the code for one or more Shader Functions.

If the library browser was shown from a layers Function, tap a Shader Function to load it in this layer.

Tap the edit button to open this Library in the built-in code editor.

The bundled Libraries are read-only and can not be edited, but you can save an editable copy of the library from the editor. You can also tap the plus button inside "iCloud" or "Local" locations of the Library Browser to create a new Library.

Long-press or right-click a library to show its context menu:

Trash: Delete this library.
Rename: Rename this library.
Share: Share/export this library.
Move to iCloud/Local: Move this library between iCloud and Local storage.
Edit Code: Open this library in the editor.

Blending

The blending mode of the Shader Layer determines how it's combined with the layer below it in the stack (or for the bottom layer, transparent black).

Layers go from bottom (background) to top (foreground), as in most other layer-based graphics software. The image flows from bottom and up through the layers before reaching the final stack output.

Note

In addition to this built-in blending, a Shader Function can also take direct color input and do its own blending or processing inside the shader code.

Tap the blend button to show the available blending presets.

Preset names with arrows indicate that Source and Destination layers are swapped.

Most presets assume pre-multiplied alpha.

Blend Bypass

Tap the toggle in the top-left of the blend menu to disable/enable blending. This is useful to temporarily disable blending.

Channel Mask

At the top of the blend menu is the channel mask, consisting of four toggle buttons for each color component: R, G, B and A. When any channel is toggled off, its value will not be changed or written to by this layer, but will keep its current value.

For example, use this to let Alpha or RGB be passed through from the layer below, or apply a color adjustment or effect on selected channels only.

Alpha = 1

Next to the mask buttons you will find a button named "A=1". When enabled, this will force the alpha output to 1.0, which is the maximum value.

For example, this can be useful on the top layer if you want to make sure the image is fully opaque before exporting it.

Note

The A=1 toggle has no effect if A is off in the Channel Mask.

Custom blending

For full control, tap the edit button in the top-right of the blend menu. This will display the blending matrix that allows you to specify a custom blend operation:

	Src x		Dest x
RGB	[ F_s ]	[ OP ]	[ F_d ]
Alpha	[ F_s ]	[ OP ]	[ F_d ]

Blending is done through the formula Out = Src * Fs OP Dest * Fd, where Src is this layer and Dest is the layer below it.

Tap the F or OP buttons to select the factors and operators.

Factors

Fs and Ds determines the factors multiplied with Src and Dest:

Factor
0	Zero
1	One
S_rgb	Source Color
1-S_rgb	1 - Source Color
S_α	Source Alpha
1-S_α	1 - Source Alpha
D_rgb	Destination Color
1-D_rgb	1 - Destination Color
D_α	Destination Alpha
1-D_α	1 - Destination Alpha
S_α⋀1-D_α	Source Alpha Saturated
C_rgb	Blend Color
1-C_rgb	1 - Blend Color
C_α	Blend Alpha
1-C_α	1 - Blend Alpha

The last four uses a separate Blend Color/Alpha, which is shown as a color slider widget, and allows user control of the blend factor value.

Operators

The operator OP is one of:

Operator
+	Src + Dest
-	Src - Dest
--	Dest - Src
⋀	MIN( Src, Dest )
⋁	MAX( Src, Dest )

Note

The Factors are ignored by the MIN and MAX operators.

Blend Groups

Sometimes you may wish to treat a chain of layers as a group, and blend their output as a whole.

In Lucinate, this is achieved by using an off-screen group buffer that exists in parallell to the normal display buffer. Shaders work on this group buffer, and when the group is finished you blend it into the display buffer using the Commit Group function. Conversely, the Display to Group function copies the current display buffer back into the group buffer.

In the example diagram above, two layers are first rendered as a group into the display, then two other layers are blended as a group into the display on top of the first group. Finally, a last layer is applied on the results.

To add a Commit Group, add a new layer and select the "Commit Group" function from the "Group" library.

Typically, the layer immediately above a Commit Group starts a new group by not reading from or blending with the current image (as indicated by the dotted lines in the diagram). However, it's also possible to start the new group by continuing from the previously committed image — blending with or processing it further.

If there is no Commit Group layer further up, the top-most ungrouped layers are applied directly to the display buffer after all groups are blended. This allows you to apply final processing layers to the result before it reaches the display.

Shader Inputs & Parameters

If the Shader Function declares any texture inputs, sampler states, or user parameters, they will show up in the layer user interface.

Long-press or right-click the parameter title for a context menu where you can reset it to default values.

Shader Parameters

Parameters allows user control of variables in the Shader Function, via sliders and toggles etc. They are declared in the Shader Function.

You can double-tap number boxes and slider value labels for a numeric entry popup.

If the parameter supports modulation, a triangle indicator will be shown to the left of the parameter title.

Texture Inputs

Texture input buttons shows the currently selected texture source for that input. If the selected texture is mipmapped, the button text has a small triangle prepended.

Tap a texture input to show the texture grid view, which allows you to select a texture source to use for this input.

The texture grid view has the following tab sections:

Stacks: Use the final output of a stack as a texture. This also includes Previous Pass, which will use the output of the previous pass in this stack as a texture.
Camera: Use the live video from a connected or built-in camera as a texture.
User Media: Use a video or image file as a texture. Right-click or long-press and select Replace to replace this texture.

Tap the plus-button to add a new user texture from imported or bundled files.

Tap outside of any texture grid cell to select None, which is a transparent black 1x1 texture.

Most texture sources have settings. Right-click or long-press and select Settings to access them.

Note

The Previous Pass is typically the previous output frame, useful for feedback-effects. If the stack contains an End Pass or Commit Pass layer, this texture will contain the result of that pass.

Sampler State

When using a texture, a sampler state object is used to configure how the texture is sampled. These can be defined programatically in the shader function, or exposed as a user parameter with the following options:

Filter

Decides the behaviour when scaling a texture.

Filter Nearest: Nearest pixel is used.
Filter Linear: Linear filtering is used.

Address mode

Decides the behaviour when sampling coordinates outside the (0,0) to (1,1) bounds.

Clamp to Edge: Clamps to the color at the edge of the texture.
Repeat: Repeats the texture.
Mirror Repeat: Repeat with mirroring.
Clamp to Zero: Clamps to transparent black.

Audio Inputs

When the shader uses audio input arguments such as audio::env or audio::fft, they will expose an Audio Analyzer button that allows you to select which analyzer instance this shader input should connect to.

All but audio::wave will also show a dB gain setting that can be used to adjust the gain of this input.

Tap the Project button in the main toolbar to open the Project Menu.

Project

Title: Project title. Tap the button for rename, trash, and further options.
New: Create new project.
Open: Open existing project.
Close: Close this project and show the Launch screen.

Help

Users Guide: Show the bundled Users Guide.

Resources

Textures Sources: This opens a list of all texture sources, where you can add, replace or delete user textures or change settings for textures.

Info

Displays various info about the GPU and app.

Tap the menu button in the main toolbar to open the Settings Menu.

Main Output

External Display / Display Window: On iPad and iPhone, toggles between external display (enabled) and standard screen mirroring (disabled). On Mac, toggles a separate display window that can be moved to an external screen.
Black on Pause: When enabled, the external display is black while main timeline is paused.
Ext Screen Mode: If an external display is in use, this shows the available screen modes and allows you to change it.

Render Target

Resolution: Render resolution. Tap to change resolution.
Orientation: The orientation and aspect ratio of the current resolution. Tap to flip orientation.
Framerate: The preferred framerate, synchronized to the current display. The available options are integer divisions of the maximum rate of the display.
Colorspace: Set colorspace. DisplayP3 is a wide-gamut colorspace that allows deeper colors if your display supports it. Any Image or Camera texture sources will automatically adapt or convert as needed.

Audio & MIDI

Audio Input: Configure audio settings and Audio Analyzers.
MIDI Input: Select CoreMIDI source for MIDI inputs.

Previews

Dynamic Range: Enable extended dynamic range (HDR), showing color values above 1.0 for displays that supports it.
Background Style: Set the background style of stack output views when they are not in Opaque mode.
Background Gray: Background grayscale level of stack output views.
Min Filter: Set filter used when content is scaled down.
Mag Filter: Set filter used when content is scaled up.

Code Editor

Tap the Edit button in the main toolbar to show the code editor, where you can edit libraries of shader code on-the-fly.

Library Title

Tap the current library title at the top of the editor to show the library browser.

Build

Save and re-compile the code. Any Layers using this library will reload their Shader Functions automatically.

Menu

Show editor menu:

Open...: Show the shader library browser to load a shader library or include file into the editor.
Save Copy: Save an editable copy of this library.
Revert to saved: Discard any edits and reload from saved.
Settings: Change editor settings such as text font and color scheme.
Find: Find (and replace) text.
Search Help: Open the Function Reference help page. If any text is selected, it will be entered in the help search field.

Syntax Coloring

You can add custom syntax color schemes by adding .json files in a "ColorSchemes" subfolder of the apps documents folder.

Example:

"background": "#131313",
"nonwords": "#ffffff",
"comments": "#7c7367",
"default": "#bfbfbf",
"functions": "#47b0b7",
"keywords": "#3d8fd1",
"types": "#3dd17f",
"brackets": "#ccaa70",
"preproc": "#b76040",
"selection": "#777777"

Grid View

Tap the Grid button to show the grid view.

Tap a grid cell to quickly scroll to that strip. Long-press a cell to select it as Main Output.

Modulation

Parameters can be affected by Modulators.

Modulators

Modulators such as LFOs and Audio Envelope followers can be created by tapping the Modulator button at the bottom of the Stack.

There are fixed global Modulators for MIDI. Make sure you have a MIDI source connected to the global MIDI Input in the Settings Menu.

Each Modulator can have multiple outputs. For example, the MIDI CC modulators have one output per CC (0-127), and LFOs have one Unipolar and one Bipolar output.

Parameter Modulation

If the parameter supports modulation, a triangle indicator () will be shown to the left of the parameter title.

Tap a parameter title to show the modulation view for the parameter.

Vector parameters will have one modulation input per component. For example, an RGBA Color will have four inputs: R, G, B and A.

The modulation view will show one section for each modulation input of the parameter, each section consisting of the following elements:

Main Modulator: Tap the modulator button to select a main Modulator. Tap the output button to select which output of the modulator to use.
Via Modulator: Tap the modulator button to select a Via Modulator. For numeric parameters, the Main Modulator value will be multiplied with the value of the Via Modulator. For boolean parameters, the Threshold will be multiplied with the value of the Via Modulator.
Amount (For numeric parameters): Set the modulation amount, in the parameter's own units. The modulation value will be multiplied by this and then added to the initial parameter value.
Threshold (For boolean and trigger parameters): Set the threshold for when the modulation value will flip the boolean parameter state.
Boolean Op (For boolean parameters): Decides if the modulation should AND, OR or XOR (invert) with the initial parameter state.
Meter: A horizontal bar showing the current modulation value resulting from the selected Main and Via Modulator.

External Display

External display is supported on both iPad, iPhone and Mac.

If External Display / Display Window is enabled in settings, the strip with selected Main Output button will be shown on the external display (iPad and iPhone) or in the separate display window (Mac).

On iPad and iPhone, connect a display via a suitable adapter (HDMI), or use AirPlay screen mirroring to an Apple TV or similar.

On Mac, drag the display window into your external display and fullscreen it.

When an external display is used, the rendering is synchronized to that display.

Video Recording

Tap the Record button in the main toolbar to show the video recording settings.

The Status section will indicate if there is a recording in progress or if it's ready to start recording. If ready, tap Start to start recording. If already recording, tap Stop to stop recording.

The current stack selected as Main Output will be recorded. This can be switched on-the-fly while recording. If no stack is selected, the video will record black frames.

Input

Video Source: Select which stack to record. This also changes Main Output stack.
Audio Source: Select the Audio Source to record.

Video Format

File Type: Choose video container file type.
Codec: Choose video codec. Not all codecs are available on all device models.
Resolution: Choose custom resolution or use the project render target resolution.
Dynamic Range: Enable High Dynamic Range, encoding color values above 1.0. Uses HLG transfer curve. HEVC 10 Codec highly recommended to avoid banding.

Audio Format

Sample Rate: Set target audio sample rate. If the Audio Source provides a different sample rate, it will be converted. The sample rate matching the current Audio Source is marked with an asterix.
Codec: Set audio codec. AAC, ALAC or Linear PCM.

Video Compression

Bitrate: Choose between Automatic and Manual bitrate mode.
Quality: Shown when Bitrate mode is Automatic. The bitrate varies to keep a constant quality. Complex frames will take more space than simple ones. Only available for HEVC codecs.
Mbit/s: Shown when Bitrate mode is Manual. Enter the target average bitrate in Mbit/s.
B-Frames: Allow bi-directional frames. When enabled, frames can be reordered for better compression.

Beat Sync

Tap the Tempo button in the main toolbar to configure the Beat Clock, where you can set tempo and sync options.

There are two time sources available in the app:

Main timeline (seconds)
Beat Clock (beats)

Shader time parameters can be set to follow Beats instead of Seconds. Tap a time parameters / Clock button to configure its clock source and other settings.

The Beat Clock can be externally synchronized with Ableton Link or MIDI Clock.

Audio Analyzers

Shaders with audio inputs (such as audio::fft) connect to Audio Analyzers, which provide waveform, FFT and envelope follower data to the shader input.

Tap Audio Inputs in the Audio & MIDI settings page to view and configure Audio Analyzers.

By default there is a single analyzer, but you can tap the plus button to create additional ones.

Each Analyzer in turn connects to an Audio Source, such as hardware audio interface inputs or Ableton Link Audio channels. Tap the source button to show a menu of available audio sources.

Right-click or long-press an Analyzer to change its settings (such as FFT size) or remove it. An analyzer can't be removed while assigned to any existing shader audio input in the project.

The full signal flow looks like this:

Audio Source -> Audio Analyzer -> Audio Input (shader side)

Note

For Ableton Link Audio, you must enable both Link and Link Audio in the Ableton Link settings, reached via the Tempo button in the main toolbar.

Colorspaces

Internally, the shader stack uses a linear 16-bit floating point format. It's automatically converted to the appropriate colorspace for display and export, typically with an sRGB gamma curve. Thus, outputting a 0.5 grayscale value will be displayed as perceived middle gray.

Due to the floating point format, the image values in the stack are not bound to 0.0-1.0. This allows extended dynamic range (HDR) by generating values above 1.0 if your display supports it.

Contact

Chat & support: Lucinate Discord server
Website: kymatica.com
E-mail: info@kymatica.com

Introduction

Strips

Output View

Shader Stack

Toolbar

Preview Modes

Stack Settings

Shader Layer

Buttons

Context menu

Library Browser

Blending

Blend Menu

Blend Bypass

Channel Mask

Alpha = 1

Custom blending

Factors

Operators

Blend Groups

Shader Inputs & Parameters

Shader Parameters

Texture Inputs

Sampler State

Filter

Address mode

Audio Inputs

Project Menu

Project

Help

Resources

Info

Settings Menu

Main Output

Render Target

Audio & MIDI

Previews

Code Editor

Syntax Coloring

Grid View

Modulation

Modulators

Parameter Modulation

External Display

Video Recording

Input

Video Format

Audio Format

Video Compression

Beat Sync

Audio Analyzers

Colorspaces

Contact