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]
Classic Curve
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
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]
Sets the grid color for function in RGBA format.
gridstep_x[float]: 100.
Sets the horizontal (x) grid step for the function object's display.
gridstep_y[float]: 0.1
Sets the vertical (y) grid step for the function object's display.
legend[int]: 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]: 1.
Sets the thickness (width) of the lines drawn between points.
mode[int]: 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]: 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'
1 = 'Shift'
mousereport[int]: 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]: 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'
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.
Shadow Alpha
shadowblend[float]: 0.1
Shadow Blend
shadowproportion[float]: 0.
Shadow Proportion
shadowreflectionpoint[float]: 0.
Shadow Reflection Point
shadowsigned[int]: 0
Display Shadow as Signed Display
snap2grid[int]: 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]: 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]
JS Painter File
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 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.
- 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 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.
- 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 middle-right 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 middle-right 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 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
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 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 |