Message Principles

Sending messages is the main function of GeoSonix. They can be sent by any of cursors, triggers or curves (although each is used somewhat differently). Messages can also be sent to GeoSonix to alter its generation of messages.

While a script is running you can verify what messages are being sent or received by looking in the "Messages" section of the inspector.

All types of objects can send automessages, These are sent spontaenously at regular intervals, but only when the transport is running.
In addition to automessages, triggers send a message each tme a cursor "collides" with them.
In addition to automessages, ,urves can have "beat points" defined on them which cause the curve to send a message each time a cursor collides with a beat point on the cursor's curve. Beat points can be defined to occur at regular intervals and patterns somewhat like a step sequencer. Cursors don't activate beat points on other curves.

Cursors move along curves, and although by themselves only can generate automessages, they are important in that they can cause the triggers and curves to send their messagses.

Messages are defined as normal Javascript functions in the Script tab of the inspector. Each object has a property called "msgFunction" that is the name of the funtion it calls when triggered. This can be set in the property inspector in the "Msg Function" field. An object may have a function name defined but it has no effect unless there is a valid function by that name in the script. New cursor object have a defined function name of "cursorMessage" but you can change it as needed. The same is true for the default function names for triggers and curves.

The Patchbay

The patchbay provides a way to indirectly refer to ports in messages using the names of virtual ports that you define. This allows you to change the MIDI or OSC address to which a score's messages are sent without editing all messages in the score. It also lets you write scripts that can be reused with different synths without having to make any change to the script.

The patchbay is accessble from the GeoSonix File menu with the sequence File-Patchbay... . The Patchbay looks like this:

The dropdown lists in the MIDI section allow you to choose from the currently abailble MIDI ports on your system. No equvalent is list possibe for OSC. The system address and port number must be typed in directly. Note that 127.0.0.1 refers to the computer on which GeoSonix is currently running. You will need to look up or assign the appropriate port number for where you want the messages to go. For example the setting shown for vOsc1 (127.0.0.1:57120) will direct messages to the default port of Supercollider on your local system.

The aliases can be any string of letters and numbers that you choose, but must not start with a number and must not contain any spaces. The names VMidi1, etc are the default names, and generally it is most convenient to retain these as it may make it easier for you to share scores and scripts with other users.

A the bottom of the Patchbay dialog, a field is provided to define one MIDI in-port. The dropdown list will show the names of available ports on your system. It is also possible for you to assign the port number GeoSonix will listen for OSC messages. This can be entered in the Messages tab of the Inspector. Note that for OSC it is not necessary to assign the system address itself, just the port number, as the address will always be the UDP network address of your computer, or 127.0.0.1 if the sender is also on your computer.

It is necessary to exit from GeoSonix and restart it to cause the new patchbay settings to take effect. Patchbay assignments are saved on your system and the most recently prevailing settings are restored in the next session.

Message Parameters

In defining message behavior it is important to be able to access properties defining the state of the score at the moment the message is to be sent. The state of the score includes the location and properties of every object in the score, and global properties of the score. Most important are the properties of the object itself that generated the message. For example what the message does may be made to depend on things like the object location, the color of the pixel in image behind the object, the distanct to some other object, the velocity of the object, or many other things.

Geosonix Object Properties

In GX2 most object properties can be set and read directly as Javascript properties of the object Objects in the score can be referred to using their id using the _obj(id) function. To use the value of a property refer to it with the _obj(id) function and the name of the property.

For example to print the x coordinate of object 99 use:

print( _obj(99).x );

To set the a property you can assign to it as if it were a variable. For example to set the x position of object 99 to 3.22 use:

_obj(99).x = 3.22;

To set the message function assign the name of the function to it as a string:

_obj(99).msgFunction = "myFunction";

In the message function of an object you can refer to that object with the Javascript "this" operator. For example the following is a message function called "myMessage" that will print the coordinates of that object each time the object is triggered.

function myMessageFunction() { print(print(thix.x, this.y, this.z); }

Each time "myMessage" is called the object's properties at that instant will be used. In GX2 this technique is used to access object properties in messages, replacing the special named properties used in the old style messages. (and is much more efficient)

You can use object properties similarly to change the properties of the message object. This example sets a trigger's size to be equal to the absolute value of its x coordinate:

function myMessageFunction() { this.triggerSize = 1+abs(this.x); }

The following is a list of objects and the property you have access to and the data type of the values returned. Note that some properties that all properties can be read (accessed), but not all can be written.

Properties and Methods Shared by All Objects

The following score properties may be used for any object:

• bool selectedHover (READ) True if the mouse cursor if hovering over this object.
• bool selected (READ) True if the object is selected.
• int16 id (READ) Object id.
• String groupId (READ, WRITE) Name of the group this ob.ject belongs to, if any.
• String documentId (READ) Name of the document containing this object.
• String label (READ, WRITE) This object's label (not currently implemented).
• String posStr (READ, WRITE) Object's x, y, z coordinates as a space-delimited string.
• float x (READ, WRITE) Object's x position
• float y (READ, WRITE) Object's y position
• float z (READ, WRITE) Object's z position
• float x01 (READ, WRITE) Object's x position scaled into a range of 0 to 1 as a proportion of the background image
• float y01 (READ, WRITE) Object's y position scaled into a range of 0 to 1 as a proportion of the background image
• float r (READ) Red component of color of pixel behind object.
• float g (READ) Green component of color of pixel behind object.
• float b (READ) Blue component of color of pixel behind object.
• float a (READ) Alpha (transparency) of color of pixel behind object.
• float h (READ) Hue component of color of pixel behind object.
• float s (READ) Saturation component of color of pixel behind object.
• float v (READ) Value component of color of pixel behind object.
• bool active (READ, WRITE) Whether the object is active or not (true or false).
• bool hideInactive (READ, WRITE) Whether to hide the object when it's inactive.
• bool hideObject (READ, WRITE) Whether the object is hidden.
• String colorActive (READ, WRITE) The color of the object when it's active.
• String colorInactive (READ, WRITE) The color of the object when it's inactive.
• bool restart (READ) True only in a "restart" message. (Used only in message callbacks)
• bool start (READ) True only in a "start" message. (Used only in message callbacks)
• String type (READ) The object's type: "trigger", "curve" or "cursor"
• String msgFunction (READ, WRITE) Name of this object's message function
• int messageInterval (READ, WRITE) Automessage interval in ms for this object. Set to 0 to disable automessages.
• bool isAutoMessage (READ) True only when accessed in an autoMessage function (Used only in message callbacks).

The following method (i.e.. function call) may be used for any object:

• _obj(id).sendMessage() Cause this object to call its message function. (Useful in testing.)

Properties and Methods of Trigger Objects

The following properties and methods may be used with trigger objects:

• float triggerSize (READ, WRITE) The trigger's size.
• String textureActive (READ, WRITE) Registered image to use when this trigger is active.
• String textureInactive (READ, WRITE) Registered image to use when this trigger is inactive.
• bool restart (READ) True only in a "restart" message. (Used only in message callbacks)
• float triggerDistance (READ) Distance of the trigger from the center of the cursor that triggered it
• float beat (READ) Currently always returns 127 for triggers. Provided for message compatibility with curve messages.
• ScriptValue cursor (READ) Returns the cursor object that triggered this trigger. (Only valid in message callbacks)
• ScriptValue snapCurve (READ)Returns the curve object onto which this trigger is snapped. (Returns 0 if none)
• int32 snapPoint (READ) Returns the number of the snap point (i.e. beat point) onto which this trigger is snapped.

Properties and Methods of Cursor Objects

The following properties and methods may be used with cursor objects:

• String repeatPattern (READ, WRITE)Repeat pattern as floating point numbers in a space-delimited string.
• float startPosition (READ, WRITE)Start position of cursor on its curve
• float startTime (READ, WRITE)Time cursor should start moving in terms of the time on the main transport.
• float endTime (READ, WRITE) Time cursor should stop moving in terms of the time on the main transport.
• float startLoop (READ, WRITE)Loop (cycle) on which cursor should start moving.
• float endLoop (READ, WRITE) Loop (cycle) on which cursor should stop moving.
• bool asLoops (READ, WRITE)If true the cursor active time is in terms of loops. If false it's in terms of seconds.
• float duration (READ, WRITE)Time cursor should take to traverse its curve once if that cycle's speed multiplier is 1.
• float speedMultiplier (READ, WRITE)Speed of the cursor as a multiple of the main transport speed.
• float cursorWidth (READ, WRITE)Width of the cursor from tip to tip.
• float cursorHeight (READ, WRITE)Height of the cursor in the z direction.
• int nbLoop (READ)Count of number of time the cursor has gone around its curve
• float timeLocal (READ)Local time of the cursor (main transport time elapsed * cumulative multipliers
• float xOffset (READ)Fractional x position of cursor on its curve. Far left is 0; far right is 1.
• float yOffset (READ)Fractional y position of cursor on its curve. At bottom is 0; at right is 1.
• float zOffset (READ)Fractional z position of cursor on its curve. Lowest z level 0; highest is 1.
• float xVelocity (READ)Cursor x velocity. (only valid when transport running)
• float yVelocity (READ)Cursor y velocity. (only valid when transport running)
• float zVelocity (READ)Cursor z velocity. (only valid when transport running)
• float localTime (READ)
• float localTime01 (READ)
• float angle (READ)Angle of direction of cursor motion in degrees
• float beat (READ) If on a curve and triggered by a beat point, returns beat strength (0..127). Otherwise returns 127
• ScriptValue curve (READ)If this cursor is on a curve, returns the curve object (from which curve properties can be accessed).
• ScriptValue trigger (READ)In a collision with a trigger, returns the trigger object (from which trigger properties can be accessed).

Properties and Methods of Curve Objects

The following score parameters may be used in the definition of messages sent by cursors:

• float pathLength (READ) Length of curve (in units of time)
• String resizeStr (READ, WRITE) Curve width and height as a space-delimited string
• float size (WRITE) Curve size as a single number. (width and height both set to this value)
• float beat (READ) The strength of the beat from this beat point: 0..127 (only valid in message callbacks)
• ScriptValue cursor (READ) Cursor object of the cursor on this curve. (If more than one cursor, returns the first added)
• float height (READ, WRITE) Set just the height of this curve leaving the width unchanged.
• float width (READ, WRITE) Set just the width of this curve leaving the height unchanged.
• int nPoints (READ) Number of points defining this curve
• String beatPattern (READ, WRITE) String defining the beat points for this curve. Same format as used in inspector.
• String beatEmphasisStr (READ, WRITE) String defining the beat emphasis pattern for this curve. Same format as used in inspector.
• String activeBeats (READ, WRITE) String defining the active beats for this curve. Same format as used in inspector.
• int16 lineFactor (READ, WRITE) Specify line as dashes and spaces (see reference).
• lineStipple (READ, WRITE) Specify line as dashes and spaces (see reference).

The following methods (i.e.. function calls) may be used for curves:

• _obj(id).addPoint(x, y, z, smooth) Add the next point to a curve. If smooth set to false, curves segments are straight; if set to true the curve is smoothed. If omitted, smooth defaults to false.