function
Max Reference
Open Help

function

Breakpoint function editor

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.

Examples

Send line segment information to line~, or look up (and interpolate) individual Y values

Arguments

None.

Attributes

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.

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.

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.

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.

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]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

annotation [symbol]

Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.

background [int] (default: 0)

Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.

color [4 floats]

Sets the color for the object box outline.

fontface [int]

Sets the type style used by the object. The options are:

plain
bold
italic
bold italic

Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname [symbol]

Sets the object's font.

fontsize [float]

Sets the object's font size (in points).

Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

hidden [int] (default: 0)

Toggles whether an object is hidden when the patcher is locked.

hint [symbol]

Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.

ignoreclick [int] (default: 0)

Toggles whether an object ignores mouse clicks in a locked patcher.

patching_rect [4 floats] (default: 0. 0. 100. 0.)

Sets the position and size of the object in the patcher window.

position [2 floats]

g/s(set)

Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.

presentation [int] (default: 0)

Sets whether an object belongs to the patcher's presentation.

presentation_rect [4 floats] (default: 0. 0. 0. 0.)

Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.

rect [4 floats]

g/s(set)

Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).

size [2 floats]

g/s(set)

Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.

textcolor [float]

Sets the color for the object's text in RGBA format.

textjustification [int]

Text Justification

Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

varname [symbol]

Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.

Parameter Attributes

Order

Typeint

Sets the order of recall of this parameter. Lower numbers are recalled first. The order of recall of parameters with the same order number is undefined.

Parameter Mode Enable

Typeint

Parameter Mode Enable (not available from Parameters window)

Link to Scripting Name

Typeint

When checked, the Scripting Name is linked to the Long Name attribute.

Long Name

Typesymbol

The long name of the parameter. This name must be unique per patcher hierarchy.

Short Name

Typesymbol

Sets the short name for the object's visual display. The maximum length varies according to letter width, but is generally in a range of 5 to 7 characters.

Type

Typeint

Specifies the data type. The data types used in Max for Live are:

Float
Int
Enum (enumerated list)
Blob

Note: By convention, the Live application uses floating point numbers for its calculations; the native integer representation is limited to a range of 0-255 (similar to the char data type used in Jitter). When working with Live UI objects whose integer values are likely to be outside of the 0-255 range, the Type attribute should be set to Float, and the Unit Style attribute should be set to Int.

Range/Enum

Typelist

When used with an integer or floating point data type, this field is used to specify the minimum and maximum values of the parameter.
When used with an enumerated list (Enum) data type, this field contains a space-delimited list of the enumerated values (if list items contain a space or special characters, the name should be enclosed in double quotes).

Modulation Mode

Typeint

Sets the Modulation Mode used by the Live application. The modulation modes are:

None
Unipolar
Bipolar
Additive
Absolute

Modulation Range

Typelist

This parameter is only used with the Absolute modulation mode. It specifies defines the range of values used.

Initial Enable

Typeint

When checked (set to 1), the UI object can store an initialization value. The value is set using the Initial attribute (see below).

Initial

Typelist

Sets the initial value to be stored and used when the Initial Enable attribute is checked.

Unit Style

Typeint

Sets the unit style to be used when displaying values. The unit style values are: Int: displays integer values
Float: displays floating point values
Time: displays time values in milliseconds (ms)
Hertz: displays frequency values (Hz/kHz).
deciBel: displays loudness (dB)
%: Percentage
Pan: displays Left and Right values
Semitones: displays steps (st)
MIDI: displays pitch corresponding to the MIDI note number
Custom: displays custom data type
Native: defaults to floating point values

Custom Units

Typesymbol

Sets the units to be used with the 'Custom' unit style (see "Unit Style", above). Custom unit strings may be simple symbols (e.g. "Harmonic(s)"), in which case the parameter's value will be displayed in its 'Native' display mode, followed by the symbol (e.g. "12 Harmonic(s)" for an Int-typed parameter or "12.54 Harmonic(s)" for a Float-typed parameter). For additional control over the numerical component displayed, a sprintf-style string may be used (e.g. "%0.2f Bogon(s)", which would display a value such as ".87 Bogons").

Exponent

Typefloat

When set to a value other than 1., the parameter's input and output values will be exponentially scaled according to the factor entered in this column.

Steps

Typeint

The number of steps available between the minimum and maximum values of a parameter. For instance, if the parameter has a range from 0.-64., with Steps set to 4, the user can only set the parameter to 0, 21.33, 42.66 and 64.

Parameter Visibility

Typeint

For automatable parameters (Int, Float, Enum), 'Stored Only' disables automation, although parameter values are stored in presets. 'Hidden' causes the parameter's value to be ignored when storing and recalling data. Non-automatable parameters (Blob) are 'Stored Only' by default, and can be set to 'Hidden', if desired.

Update Limit (ms)

Typeint

Speed limits values triggered by automation.

Defer Automation Output

Typeint

Defers values triggered by automation.

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.

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

ARG_NAME_0 [int]
TEXT_HERE

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 two-item lists, containing the 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.

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.

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.

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.

(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.

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.

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.

paste

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

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.

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.

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
line Generate timed ramp