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.
Arguments
None.
Attributes
autosustain[int]: 0
Sets the sustain mode for function. There are three possible values: 'Off', 'Next-to-Last Point', and 'Any Single Point'. The default is 0 (off).
Possible values:
0 = 'Off'
Turn off sustain mode.
1 = 'Next-to-Last Point'
The next-to-last point in the function is automatically a sustain point. This setting requires that there are more than two points in the current function.
2 = 'Any Single Point'
Allows you to click on any point in the function to make it a sustain point. If autosustain is on and there is already a different point that is a sustain point, that other point will be turned off.
bgcolor[4 floats]
Sets the display color for the background in RGBA format.
classic_curve[int]
clickadd[int]: 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]: 1
Toggles a user's ability to move existing breakpoints by dragging them with the mouse. This feature is enabled by default.
clicksustain[int]: 2
The clicksustain attribute controls how you can specify sustain points with your mouse. There are three possible values: off, cmd/ctrl click, and double-click. The default value is 2 (double-click).
Possible values:
0 = 'Off'
The ability to specify sustain points with your mouse is turned off.
1 = 'Cmd/Ctrl Click'
Specify sustain points by pressing Cmd/Ctrl and clicking with your mouse.
2 = 'Double-Click'
Specify sustain points by double-clicking with your mouse.
cursor[float]: -1.
Sets the position of the cursor along the function object's X axis.
domain[float]: 1000.
Sets the maximum displayed X value.
grid[int]: 0
Sets the grid displayed behind the function
Possible values:
0 = 'Off'
(
No grid displayed
)
1 = 'Horizontal'
(
Horizontal grid displayed
)
2 = 'Vertical'
(
Vertical grid displayed
)
3 = 'Horizontal and Vertical'
(
Horizontal and vertical grid displayed
)
gridcolor[4 floats]
Sets the grid color in RGBA format
gridstep_x[float]: 100.
Sets the horizontal grid spacing
gridstep_y[float]: 0.1
Sets the vertical spacing
legend[int]: 1
Toggles the numerical display when a point is highlighted or updated
linecolor[4 floats]
Sets the display color for line segments in RGBA format
linethickness[float]: 1.
Sets the width of lines drawn between points
mode[int]: 0
Sets whether the function includes curve information. This changes both the function display and output format. When curve information is not included, the format of the second outlet is compatible with the line and line~ objects. When curve information is included, the output is compatible with the curve~ object.
Possible values:
0 = 'Linear'
(
Linear mode
)
No curve information is included or displayed
1 = 'Curve'
(
Curve mode
)
Curve information is included; the curvature of line segments can be changed with the setcurve message or by option- (alt-) dragging on a segment.
mousemode[int]: 0
The mousemode attribute determines the behavior when moving a point by dragging.
Possible values:
0 = 'Free'
1 = 'Shift'
mousereport[int]: 0
When enabled, the third outlet sends a three item list containing the current cursor position as well as the index of the current point under cursor (or -1 if the cursor is not over a point). Output occurs when the cursor is over the object in a locked patcher.
outputmode[int]: 0
param_connect[symbol]:
Establishes a two-way connection between the object and a parameter of a compatible object with parameters such as gen~ or jit.gl.slab. The object can be used to change the value of the parameter and will update if the parameter value changes. The easiest way to set param_connect is with the attribute's menu in the inspector or the Connect submenu of the Object Action menu. The menu displays all available parameters of compatible objects.
Setting the param_connect attribute with a message requires the target parameter's path, which is the host object's scriping name followed by two colons and the parameter name. For example, for a gen~ object with scripting name gen~_AB , the path of the freq parameter would be gen~_AB::freq . You can set a value for the param_connect before the host object or parameter exists, and the object will connect to the parameter once it exists. Refer to the user guide entry for param_connect for more details.
parameter_enable[int]
Enables use of this object with Max for Live Parameters and setting initial parameter values in Max.
parameter_mappable[int]: 1
When parameter_mappable is enabled, the object will be available for mapping to keyboard or MIDI input using the Mappings feature. (default = 1).
pointalign[float]: 0.
The pointalign attribute overrides the pointsize attribute for the purpose of controlling the location of points relative to the function's bounding box. Values range from 0 (no override, positioning is based on the pointsize) to 20 (where the function's points will be centered within a circle with a radius of 20 pixels).
pointsize[float]: 2.5
Sets the radius size for all points in function. This value influences the position of all points in addition to their size, so that large points are not cut off. The pointsize ranges from 1 to 20.
range[2 floats]: 0. 1.
Sets the minimum and maximum display ranges for Y values.
shadowalpha[float]: 0.
The shadowalpha attribute sets the opacity of the gradient shadow underneath the line representing the function. At 0 (the default), the gradient is invisible; at 1 it is completely opaque. shadowalpha must be non-zero for the other shadow drawing attributes to have an effect on the object's appearance.
shadowblend[float]: 0.1
Sets the amount of black blended with the object's pointcolor to create the shadow. Values of shadowblend closer to 0 will be darker; values closer to 1 will be lighter.
shadowproportion[float]: 0.
Sets the vertical mid point within the shadow gradient. 0 is at the bottom, 1 is at the top.
shadowreflectionpoint[float]: 0.
When shadowsigned is enabled, shadowreflectionpoint determines the point where the shadow is divided and reflects symmetrcially in the vertical dimension. 0 is at the bottom (with no reflection); 1 is at the top.
shadowsigned[int]: 0
When enabled, the shadow can reflect around a point (shadowreflectionpoint) to create a mirrored effect appropriate when the range of function includes negative values.
snap2grid[int]: 0
Determines whether points are constrained to grid values when they are added or moved. The behavior of snap2grid is independent of the grid visibility set with the grid attribute.
Possible values:
0 = 'Off'
(
Off
)
No grid snapping will occur
1 = 'Horizontal'
(
Horizontal Only
)
Grid snapping will occur only in the horizontal dimension
2 = 'Vertical'
(
Vertical Only
)
Grid snapping will occur only in the vertical dimension
3 = 'Horizontal and Vertical'
(
Both Horizontal and Vertical
)
Grid snapping will occur in both the horizontal and vertical dimensions
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]: 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]: 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]: 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'
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]: 0
Toggles whether an object ignores mouse clicks in a locked patcher.
jspainterfile[symbol]
You can override the default appearance of a user interface object by assigning a JavaScript file with code for painting the object. The file must be in the search path.
patching_rect[4 floats]: 0. 0. 100. 0.
Sets the position and size of the object in the patcher window.
position[2 floats]
write-only
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]: 0
Sets whether an object belongs to the patcher's presentation.
presentation_rect[4 floats]: 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]
write-only
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]
write-only
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[4 floats]
Sets the color for the object's text in RGBA format.
textjustification[int]
Sets the justification for the object's text.
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
Orderint
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 Enableint
Parameter Mode Enable (not available from Parameters window)
Link to Scripting Nameint
When checked, the Scripting Name is linked to the Long Name attribute.
Long Namesymbol
The long name of the parameter. This name must be unique per patcher hierarchy.
Short Namesymbol
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.
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 256
values, with a default range of 0-255 (similar to the char data type used
in Jitter). When working with Live UI objects whose integer values will
exceed this range, the Type attribute should be set to Float,
and the Unit Style attribute should be set to Int.
Range/Enumlist
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).
Clip Modulation Modeint
Sets the Clip Modulation Mode used by the Live application. The modulation
modes are:
None
Unipolar
Bipolar
Additive
Absolute
Clip Modulation Rangelist
This parameter is only used with the Absolute modulation mode. It specifies defines the range of values used.
Initial Enableint
When checked (set to 1), the UI object can store an initialization value. The value is set using the Initial attribute (see below).
Initiallist
Sets the initial value to be stored and used when the Initial Enable attribute is checked.
Unit Styleint
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 Unitssymbol
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").
Exponentfloat
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.
Stepsint
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 Visibilityint
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)int
Speed limits values triggered by automation.
Defer Automation Outputint
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
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 .
- x-value
[int]
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 .
- input
[float]
list
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.)
- x-value
[number]
- y-value
[number]
clear
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.
- indices
[list]
clearfix
The word clearfix clears all fix states (sets them to 0).
clearsustain
The word clearsustain clears all sustain states (sets them to 0).
color
7.0.0
The color message sets a color with an index from 0 to 15 for breakpoints and lines against a light background. It is no longer supported.
- color index
[int]
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
Outputs a series of multiple element lists describing each break point out the function object's third 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.
- receive-name
[symbol]
fix
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.
- index
[number]
- flag
[int]
getfix
The word getfix . with no arguments, will cause the function object to send a list all fix points out the object's third outlet. If an index is provided as an argument, the fix state for that point will be output.
- point-indices
[list]
getsustain
The word getsustain . with no arguments, will cause the function object to send a list all sustain points out the object's third outlet. If an index is provided as an argument, the sustain state for that point will be output.
- point-indices
[list]
lineout
The word lineout followed by either 0, 1, or no argument is equivalent to the bang message.
listdump
(mouse)
You can use the mouse to add or edit breakpoints.
- Clicking on empty space in the function adds a breakpoint. You can begin to move it immediately by dragging. Adding breakpoints can be disabled with the clickadd attribute.
- Dragging on an existing breakpoint moves the breakpoint. Modifying breakpoints can be disabled with the clickmove attribute.
- Shift-clicking on a breakpoint deletes it.
- Command- (Mac OS) or control-clicking (Windows) on a breakpoint toggles the sustain property of the point. Sustain point click behavior can be set with the clicksustain attribute.
- If the mode attribute has been set to Curve, option- (alt- on Windows) dragging on a line segment modifies the curvature of that segment.
next
The next message sends a list out the second outlet that continues 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
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.
- index
[int]
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
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.
- x-y-coordinate-pairs
[list]
setcurve
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.
- index
[int]
- curve-factor
[float]
setdomain
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.
- maximum
[float]
setrange
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.
- minimum
[number]
- maximum
[number]
sustain
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.
- index
[int]
- flag
[int]
xyc
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.
- x-value
[number]
- y-value
[number]
- curve-factor
[float]
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 third 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 |