ScinServer

See also: ScinServerOptions

Description

This class is analagous to the SuperCollider Server class. It is a client-side representation of an instance of the Scintillator video synthesis server.

Class Methods

ScinServer.default

ScinServer.default = value

Get or set the default Scintillator server. This is the server reference that will be used as the default in all server arguments to ScinthDef and others that accept an optional server argument. By default is the local server instance.

ScinServer.new(options)

Creates a new ScinServer instance. For now only local servers are supported.

Arguments

options

An optional instance of ScinServerOptions. If nil, an instance of ScinServerOptions will be created using the default values.

Instance Methods

.boot

It not already booted, boots the Scintillator synthesis server.

.numberOfWarnings

Returns the current number of errors reported by the server since boot.

.numberOfErrors

Returns the current number of errors reported by the server since boot.

.options

Provides access to the ScinServerOptions object that was or will be used to boot the Server. This allows for convenient modifications of the options before boot, without having to create a separate ScinServerOptions object to provide on the call to new().

.defaultGroup

On boot ScinServer creates this group. It is the group that by default any new groups or Scinths will be added to. It is also the group that is emptied when Cmd+Period is pressed.

.logLevel = level

Updates the logging level on the server to the provided argument. Lower log levels are inclusive of all higher log levels, so they tend to log more, and the highest log level turns off logging. This overrides any command-line argument supplied to scinsynth at startup.

Arguments

level

The values for the log level are as follows:

.screenShot(fileName, mimeType, onReady, onComplete)

Requests the server to take a screen shot of the next frame rendered, encode it into the provided file format, and save to disk.

Arguments

fileName

A string with the full path and file name, including extension, of the desired file to save the screenshot image to.

mimeType

An optional string. A hint to the image encoder as to which file format is desired, for example "image/png", "image/gif", "image/jpeg".

onReady

An optional function to call when the ScinServer responds that it has enqueued the screenshot for encode on the next rendered frame.

onComplete

An optional function to call when the ScinServer responds that it has completed encoding and writing the image to disc.

.advanceFrame(num, denom)

If the server is configured with zero frame rate, will advance the time on the synth by the provided fraction of time in seconds and render a new frame. Otherwise this command is ignored.

Arguments

num

An integer representing the numerator in the fraction of time to advance the frame by.

denom

An integer representing the denominator in the fraction of time to advance the frame by. Sending time in terms of fractions allows for traditional media frame rates (like 24 frames per second).

.dumpOSC(on)

Controls if the server should dump received OSC messages to the log or not.

Arguments

on

A boolean. If true, the server will start dumping incoming OSC messages to the log. If false, the server will stop.

.sendMsg(… msg)

Sends the provided arguments as an OSC message to the associated server process.

Arguments

… msg

The OSC message to send, typically starting with an OSC path like /scin_logLevel. For documentation about supported command consult the Scintillator Scinth Server Command Reference.

.serverBooting

Returns true if the server is in the process of booting, specifically that the ScinServer instance object has started the server but not yet heard back a response to the status polling.

.quit

Requests the server stop immediately.

.doWhenBooted(onComplete)

Adds the provided function to the list of functions to be called after the ScinServer instance object detects that the server has booted.

Arguments

onComplete

A function, the method to be called when boot is detected. The function is called with one argument, which is the ScinServer object which just booted.

.serverRunning

Returns true if the server associated with this ScinServer instance object is currently running.

.waitForBoot(onComplete)

Convenience method that adds the provided function to the boot callbacks list and then boots the server if it is not currently running.

Arguments

onComplete

The function to call when the server is detected as booted. The function is called with one argument, the ScinServer object which just booted.

.reorder(nodeList, target, addAction: ‘addToHead’)

Moves a list of nodes in order to a new location. This is used to control rendering order, an important consideration when blending between Scinths.

Arguments

nodeList

The list of ScinNodes, in order, to move.

target

An optional ScinNode, The target node to move the list of nodes relative to. If nil the target will be the defaultGroup on the server.

addAction

An optional symbol describing which behavior to use when placing the nodes. If nil the default is \addToTail.

Synchronous Commands

The server provides support for waiting on the completion of asynchronous OSC-commands such as reading or writing sound files, making them synchronous.

Note

The following methods must be called from within a running Routine . Explicitly passing in a Condition allows multiple elements to depend on different conditions. The examples below should make clear how all this works.

.sync(condition)

Sends a request to the server to finish all asynchronous commands, such as compiling a ScinthDef or decoding an image. Will block the calling thread until the completion of all pending tasks is reported by the server.

Arguments

condition

An optional Condition to use to block the Routine. If not provided ScinServer will make a new one for use.

.queueScreenShotSync(fileName, mimeType, onComplete, condition)

Call from a Routine . Requests the server take a screenshot and blocks the calling thread until the screenshot is queued to render on the next frame.

Arguments

fileName

A string containing the path and file name to save the resulting image to.

mimeType

An optional string with a mime type to provide additional context to the image encoder (in addition to the fileName extension) about what image encoding type is requested for saving the image as.

onComplete

An optional function to callback when the screenshot has been completed, meaning the render has completed and the file has been saved to disc.

condition

An optional Condition object to use to wait on. If not provided ScinServer will create its own.

.bootSync(condition)

Boot the server, then block the Routine until the server is detected as having booted.

Arguments

condition

An optional Condition object to use to wait on. If not provided ScinServer will create its own.

Developer and Diagnostic Commands

.postCrashReports

Requests the server to post some detail about any server crash reports that have been stored in the crash report database. Will produce output in the post window that looks something like:

[1594932178.669] 285299 [info] Crash report database contains 3 reports:
[1594932178.669] 285299 [info]     id: 1a77de76-f2c2-4b22-9d2a-bd5016772a2f, on: Thu 16 Jul 13:26:37 2020, uploaded: no
[1594932178.669] 285299 [info]     id: bac6608c-05cd-4f03-827b-780588d5ee1c, on: Thu 16 Jul 13:07:48 2020, uploaded: no
[1594932178.669] 285299 [info]     id: 250c0c0d-8b2c-4a16-8240-576cc26e80d1, on: Thu 16 Jul 13:14:25 2020, uploaded: yes

The id field can be copied and pasted into a request to upload individual crash reports, as well as posted in bug reports to the Scintillator developers.

.uploadCrashReport(id)

Marks a crash report as ok to upload. The reports will generally be uploaded shortly after the next time the Scintillator Server boots, assuming the computer is connected to the internet and the crash report server is available.

Arguments

id

A string with the complete crash report id.

.uploadAllCrashReports

Marks all un-uploaded crash reports with a request for upload.

Examples

// This example starts a ScinServer configured to render offscreen into a 1024x768 image buffer.
// It creates a new monochrome ScinthDef, makes a Scinth instance of it, renders a single frame,
// requests a screenshot, renders a frame which is saved as that screenshot, changes a parameter
// on the running Scinth, takes another screenshot, then quits the server.
(
~scinOptions = ScinServerOptions.new;
~scinOptions.frameRate = 0;
~scinOptions.width = 1024;
~scinOptions.height = 768;
~scinOptions.logLevel = 2;
~scinOptions.createWindow = false;
~scinOptions.swiftshader = true;

// Run on a Routine so we can use the blocking
fork {
    var c, f;
    c = Condition.new;
    f = { c.test = true; c.signal; };

    // Boot the server, and wait for it to boot.
    ~videoServer = ScinServer.new(~scinOptions).bootSync;

    // Send a ScinthDef to the server
    ~def = ScinthDef.new(\t, { |sx = 1.0, sy = 2.0|
        VBWOut.pr(VSinOsc.pr(1.0, VLength.pr(VNormPos.pr * VVec2.pr(sx, sy))));
    }).add;

    // Wait for the server to complete building the ScinthDef just provided.
    ~videoServer.sync;

    // Start rendering an instance of the ScinthDef on next frame render.
    ~scinth = Scinth.new(\t);

    // Render one frame, then advance time by 1/24th of a second.
    ~videoServer.advanceFrame(1, 24);

    // Queue a screenshot request for render, wait until queuing is complete.
    c.test = false;
    ~videoServer.queueScreenShotSync("test1.png", "image/png", onComplete: f);

    // Render a frame, to capture the screenshot.
    ~videoServer.advanceFrame(1, 24);

    // Block until the onComplete function is called, which will clear the
    // Condition.
    c.wait;

    // Set a parameter on the running Scinth.
    ~scinth.set(\sx, 2.0, \sy, 1.0);
    ~videoServer.advanceFrame(1, 24);

    // Request another screenshot.
    c.test = false;
    ~videoServer.queueScreenShotSync("test2.png", "image/png", onComplete: f);
    ~videoServer.advanceFrame(1, 24);
    c.wait;

    // Exit the server.
    ~videoServer.quit;
};
)