mc.function Reference

Breakpoint function editor

mc.function

Description

Draw or store a set of x, y points as floating-point numbers. The output the entire function is useful as an input for line~. You can also get an interpolated y value for any x value.

Arguments

None.

Attributes

annotation_name [symbol] (default: )

Info View Title

autosustain [int] (default: 0)

Toggles setting the sustain point to the one before last point. This feature requires that there are more than two points in the current function. The default is 0 (off).

bgcolor [4 floats]

Sets the display color for the background in RGBA format.

candycane [int] (default: 1)

Enables the function object to use multiple colors for drawing the lines of different functions in mc mode, with the color pattern repeating (like the stripes in a candycane) every N functions (indicated by the integer argument). Up to 8 different colors can be specified.

candycane2 [4 floats]

Specifies the 2nd line color in candycane mode in RGBA format.

candycane3 [4 floats]

Specifies the 3rd line color in candycane mode in RGBA format.

candycane4 [4 floats]

Specifies the 4th line color in candycane mode in RGBA format.

candycane5 [4 floats]

Specifies the 5th line color in candycane mode in RGBA format.

candycane6 [4 floats]

Specifies the 6th line color in candycane mode in RGBA format.

candycane7 [4 floats]

Specifies the 7th line color in candycane mode in RGBA format.

candycane8 [4 floats]

Specifies the 8th line color in candycane mode in RGBA format.

chans [int] (default: 1)

Sets the number of channels for mc.function. You can switch the displayed channel by clicking on the circles at the bottom of the object's UI, or by using the displaychan attribute.

clickadd [int] (default: 1)

Toggles a user's ability to create new breakpoints by clicking and dragging with the mouse. This feature is enabled by default.

clickinactive [int] (default: 0)

The attribute clickinactive allows you to click on an inactive function (a function on a different channel than is currently displayed) and either make that the active function ("Select" mode), or make that the active function AND start editing the breakpoint right away ("Edit" mode).

Possible values:

0 = 'Off'
Disables the ability to click on an inactive function.

1 = 'Select'
Enables the ability to click on an inactive function. When an inactive function is clicked, that then becomes the active function.

2 = 'Edit'
Enables the ability to click on an inactive function and start editing. When an inactive function is clicked, that then becomes the active function and you can immediately start editing the breakpoint.

clickmove [int] (default: 1)

Toggles a user's ability to move existing breakpoints by dragging them with the mouse. This feature is enabled by default.

clicksustain [int] (default: 1)

Click-to-sustain flag

cursor [float] (default: -1.)

Sets the position of the cursor along the function object's X axis.

displaychan [int] (default: 1)

The displaychan attribute sets the channel to be displayed.

domain [float] (default: 1000.)

Sets the maximum displayed X value.

grid [int] (default: 0)

Enables and selects the display of a grid for the function object display. The modes are:

0: No grid displayed (default).
1: Horizontal grid displayed.
2: Vertical grid displayed.
3: Horizontal and vertical grids displayed.

Possible values:

0 = 'Off'
1 = 'Horizontal'
2 = 'Vertical'
3 = 'Horizontal and Vertical'

gridcolor [4 floats]

Grid Color

gridstep_x [float] (default: 100.)

Sets the horizontal (x) grid step for the function object's display.

gridstep_y [float] (default: 0.1)

Sets the vertical (y) grid step for the function object's display.

legend [int] (default: 1)

Toggles the numerical display (legend) of the function object, displayed when a point is highlighted or updated.

linecolor [4 floats]

Sets the display color for the function line segments in RGBA format.

linethickness [float] (default: 1.)

Sets the thickness (width) of the lines drawn between points.

mode [int] (default: 0)

Selects the function object's drawing mode. The modes are:

0: Linear mode (default).
1: Curve mode. The amount of curve between each point is set using the setcurve message.

Possible values:

0 = 'Linear' ( Linear mode )
1 = 'Curve' ( Curve mode )

mousemode [int] (default: 0)

This attribute changes the behavior of what happens when moving a function point via the mouse. When mousemode is set to 'free' (default), the point being moved can only be moved between the preceding and subsequent points, and all other points are unchanged. When mousemode is set to 'shift', all subsequent points are moved an equal amount on the x axis, keeping their relative distance on the x axis from the point being moved.

Possible values:

0 = 'free' ( Move point without moving others )
1 = 'shift' ( Move point and shift subsequent points )

mousereport [int] (default: 0)

When mousereport is set to 1, a three item list of mouse data is output from the third outlet. The list contains the mouse's current position on the x and y axis, as well as the current point under the mouse pointer. If no point is under the mouse, a -1 is output. The list is only output when the mouse is over the function object and the patcher is locked.

outputmode [int] (default: 0)

Sets the function object's output mode.
Normal: When the object receives a bang, it outputs a list of the current breakpoints formatted for use by the line~ object.
List: When the object receives a bang, it sends its values in single list in which the first Y value is followed by a 0, followed by any additional Y values and associated times.

Possible values:

0 = 'Normal'
1 = 'List'

parameter_enable [int]

Enables use of this object with Max for Live Parameters and allows for setting initial parameter values in the Max environment.

parameter_mappable [int] (default: 1)

When parameter_mappable is enabled, the object will be available for mapping to keyboard or MIDI input using the Mappings feature.

range [2 floats] (default: 0. 1.)

Sets the minimum and maximum display ranges for Y values.

snap2grid [int] (default: 0)

Enables and selects a snap to grid mode for the placement of function points. Snap to grid may be enabled even when the grid is not displayed (set using the grid attribute. The modes are:

0: Snap to grid disabled (default).
1: Snap to horizontal grid.
2: Snap to vertical grid.
3: Snap to horizontal and vertical grids.

Possible values:

0 = 'Off'
1 = 'Horizontal'
2 = 'Vertical'
3 = 'Horizontal and Vertical'

style [symbol] (default: )7.0.0

Sets the style to be applied to the object. Styles can be set using the Format palette.

textcolor [4 floats]

Sets the display color for text in RGBA format.

zoom_x [2 floats] (default: 0. 1.)

Sets the horizontal zoom for the function object's display. Zoom values are set using a pair of floating point values in the range 0.0 - 1.0.

zoom_y [2 floats] (default: 0. 1.)

Sets the vertical zoom for the function object's display. Zoom values are set using a pair of floating point values in the range 0.0 - 1.0.

Common Box Attributes

Parameter Attributes

Messages

bang

Triggers a list output of the current breakpoints from the middle-left outlet formatted for use by the line~ object. As an example, if the function contained breakpoints at X = 1, Y = 0; X = 10, Y = 1; and X = 20, Y = 0, the output would be 0, 1 9 0 10. If the optional output mode is enabled, the output would be 0 0 1 9 0 10.

If there are any sustain points in the function, bang outputs a list of all the points up to the sustain point. Additional points in the function, up to a subsequent sustain point or the end point, whichever applies, can be output by sending the next message. See the description of the next and sustain messages for additional information.

int

Arguments

x-value [int]
The value is taken as an X value and outputs a corresponding Y value out the left outlet. The Y value is produced by linear floating-point interpolation of the function. If the X value lies outside the first or last breakpoint, the Y value is 0.

float

Arguments

input [float]
The value is taken as an X value and outputs a corresponding Y value out the left outlet. The Y value is produced by linear floating-point interpolation of the function. If the X value lies outside the first or last breakpoint, the Y value is 0.

list

Arguments

x-value [number]
y-value [number]
If the list contains two values, a new point is added to the function. The first value is X, the second is Y.

If the list contains three values, an existing point in the function is modified. The first value is the index (starting at 0) of a breakpoint to modify, the second is the new X value for the breakpoint, and the third is the new Y value for the breakpoint. (If the index number in the list refers to a breakpoint that does not exist, the message is ignored.)

clear

Arguments

indices [list]
The word clear by itself erases all existing breakpoints. The word clear can also be followed by one or more breakpoint indices (starting at 0) to clear selected breakpoints.

clearchans

Arguments

channels [list]
The message clearchans, followed by a list, clears all points from the specified channels.

clearfix

The word clearfix clears all fix states (sets them to 0).

clearsustain

The word clearsustain clears all sustain states (sets them to 0).

color7.0.0

Arguments

color index [int]
The message color, followed by an integer from 0-16, sets the color scheme for the function object. Each integer from 0-16 sets a different line color, while the grid color is always set to white, the text color is always set to black, and the background color is always set to grey.

copy

The copy message copies all of the current function points to the clipboard so that they can be pasted into another function object.

dump

Arguments

receive-name [symbol]
Outputs a series of multiple element lists describing each break point out the function object's middle-right outlet. Each list contains the breakpoints X and Y values, followed by the curve value, if present. An optional symbol argument can be used to specify a receive objects as a destination.

fix

Arguments

index [number]
flag [int]
The word fix, followed by a number specifying the index of a point and 0 or 1, prevents the user from changing the point if the second number is 1, and allows the user to change the point if the second number is 0. By default, points are moveable unless clickmove 0 has been sent to disable moving of all points.

getfix

Arguments

point-indices [list]
The word getfix. with no arguments, will cause the function object to send a list all fix points out the object's middle-right outlet. If an index is provided as an argument, the fix state for that point will be output.

getsustain

Arguments

point-indices [list]
The word getsustain. with no arguments, will cause the function object to send a list all sustain points out the object's middle-right outlet. If an index is provided as an argument, the sustain state for that point will be output.

lineout

Arguments

channel [int]
The message lineout, followed by an integer specifying the channel index, is equivalent to the bang message for that channel.

listdump

Arguments

receive-name [symbol]
Outputs a single list which contains all X and Y values for each of the breakpoints out the function object's middle-right outlet.An optional symbol argument can be used to specify a receive objects as a destination.

(mouse)

You can use the mouse to draw points in a line segment function; the finished function can then be sent to a line~ object for use as a control signal in MSP. Clicking on empty space in the function adds a breakpoint, which you can begin to move immediately by dragging (unless function has been sent the clickadd 0 message). Clicking on a breakpoint allows you to move the breakpoint by dragging (unless function has been sent the clickmove 0 message). The X and Y values of the breakpoint are displayed in the upper part of the object’s box. Shift-clicking on a breakpoint deletes that point from the function. Command-clicking on Macintosh or Control-clicking on Windows on a breakpoint toggles the sustain property of the point. Sustain points are outlined in white. Whenever an editing operation with the mouse is completed, a bang is sent out the right outlet.
Points with a Y value of 0 are outlined circles; other points are solid. This allows you to see at a glance whether a function starts or ends at Y = 0.

next

The next message continues a list output from the sustain point where the output of the last bang or next message ended. For instance, if the function contained breakpoints at (a) X = 1, Y = 0; (b) X = 10, Y = 1; and (c) X = 20, Y = 0, and point b was a sustain point, a bang message would output 0, 1 9 and a subsequent next message would output 1, 0 10. After a next message reaches the end point, a subsequent next message is equivalent to a bang message. next is also equivalent to a bang when no bang has been sent that reached a sustain point, or when a function contains no sustain points.

nth

Arguments

index [int]
The word nth, followed by a number, uses the number as the index (starting at 0) of a breakpoint, and outputs the Y value of the breakpoint out the left outlet. If no breakpoint with the specified index exists, no output occurs.

paste

The paste message pastes all of the points of a previously copied function into a function object.

quantize_x

This message will cause all of the points to automatically snap to the horizontal grid as defined by the gridstep_x attribute.

quantize_y

This message will cause all of the points to automatically snap to the vertical grid as defined by the gridstep_y attribute.

set

Arguments

x-y-coordinate-pairs [list]
Given the number of points already defined within function 's graphic editor, a corresponding list of x-y-coordinate pairs will set the position of each point.

setcurve

Arguments

index [int]
curve-factor [float]
The word setcurve, followed by an integer that specifies the index of a function point (numbered from 1) and a floating point value that specifies a curve, will create a curved line segment between the specified point and the next point.

Curve factor values from 0 to 1.0 produce an "exponential" curve when increasing in value and values from -1.0 to 0 produce a "logarithmic" curve. The closer to 0 the curve parameter is, the closer the curve is to a straight line, and the farther away the parameter is from 0, the steeper the curve. The mode attribute must be set to 1 (curve mode) for this message to be effective.

setdomain

Arguments

maximum [float]
The word setdomain, followed by a float or int value, sets the maximum displayed X value, then modifies the X values of all breakpoints so that they remain in the same place given the new domain.

setrange

Arguments

minimum [number]
maximum [number]
The word setrange, followed by two float or int values, sets the minimum and maximum display range for Y values, then modifies the Y values of all breakpoints so that they remain in the same place given the new range.

setvalue

Arguments

channel-value [list]
The word setvalue, followed by both a channel index (starting at 1) and X/Y coordinates, creates a new point on the specified channel. setvalue 0, followed by X/Y coordinates, creates a new point on all channels.

sustain

Arguments

index [int]
flag [int]
The word sustain, followed by number specifying the index of a point and zero or one, turns that point into a sustain point if the second number is 1, or into a regular point if the second number is 0. By default, points are regular (non-sustain). The behavior of sustain points is discussed in the description of the bang message above. Command-clicking on Macintosh or Control-clicking on Windows also toggle the sustain property of a point.

target

Arguments

channel [int]
The target message, followed by an integer, sets the channel to which incoming messages are applied.

xyc

Arguments

x-value [number]
y-value [number]
curve-factor [float]
The word xyc, followed by an two numbers that specifies X and Y values and a floating point number that specifies a curve factor, will add a new point with curve information to the function.

Curve factor values from 0 to 1.0 produce an "exponential" curve when increasing in value and values from -1.0 to 0 produce a "logarithmic" curve. The closer to 0 the curve parameter is, the closer the curve is to a straight line, and the farther away the parameter is from 0, the steeper the curve. The mode attribute must be set to 1 (curve mode) for this message to be effective.

Output

bang

Out right outlet: When a mouse editing operation is completed, a bang is sent out.

float

Out left outlet: The interpolated Y value is sent out in response to a float or int X value received in the inlet; or a stored Y value is sent out in response to an nth message.

list

Out middle-left outlet: When bang is received, a list containing information about all stored values will be sent out the outlet. This format is intended for input to the line~ object.

If the function object is in linear mode (set via the mode attribute), a float is sent out for the first stored Y value, followed by a list containing pairs of numbers indicating each subsequent stored Y value and its transition time (the difference between X and the previous X). If the function object is in linear mode (set via the mode attribute), a float is sent out for the first stored Y value, followed by a list containing pairs of numbers indicating each subsequent stored Y value and its transition time (the difference between X and the previous X).

If the function object is in curve mode (set via the mode attribute), a float is sent out for the first stored Y value, followed by a list containing triplets of numbers indicating each subsequent stored Y value, its transition time (the difference between X and the previous X), and a curve factor value (see the setcurve message listing).

Out middle-right outlet: If the function object is in linear mode (set via the mode attribute), a series of two-item lists containing the X and Y values of each of the function object's breakpoints is sent out when a dump message is received.

If the function object is in curve mode (set via the mode attribute), a series of three-item lists containing the X and Y values and a curve factor of each of the function object's breakpoints is sent out when a dump message is received.

See Also

Name Description
MC MC
line