ref: 307ba8a8d9d7c0088462bc4e947639b4593ce597
dir: /slug.man/
.TH SLUG 1 .SH NAME slug \- visual programming in lua .SH SYNOPSIS .B slug [ .I file ] .SH DESCRIPTION .PP .I slug executes the lua script .I file and will first call, if it exists, the .IR setup function and then call the .IR draw function in a loop. All available variables and functions are detailed in the sections below. .SS Structure .TP \f5setup() .I Setup is called once when the script is started. It is useful to do some initialization like setting the canvas size. .TP \f5draw() .I Draw is called directly after .I setup() and is run in a loop until program exits or .I noLoop() is called. .TP \f5noLoop() Disables the animation loop, meaning that .IR draw will only be called once. This function should be called from .IR draw to ensure it is called at least once. .TP \f5loop() Enables the animation loop. .SS Color .PP All color related functions accept either one or three arguments. If a single number is passed it is used as a shade of gray from black (0) to white (255). If three arguments are passed they are used as either an RGB (default) or HSB triplet. This can be changed with the .I colorMode function. .TP \f5colorMode(\f2mode\fP) Change the interpretation of color parameters. .PD 0 .I mode can have the following values: .PD 0 .TP .B RGB colors are defined by a combination of red, green and blue each in the range [0;255] .PD 0 .TP .B HSB colors are defined by their hue (range [0;360]), saturation (range [0;100]) and brightness (range [0;100]) .PD .TP \f5background(\f2gray\fP) .PD 0 .TP \f5background(\f2v1\fP, \f2v2\fP, \f2v3\fP) Sets the background color of the .IR slug canvas. .PD .TP \f5fill(\f2gray\fP) .PD 0 .TP \f5fill(\f2v1\fP, \f2v2\fP, \f2v3\fP) Sets the color used to fill shapes .PD .TP \f5noFill() Disable filling shapes .PD .TP \f5stroke(\f2gray\fP) .PD 0 .TP \f5stroke(\f2v1\fP, \f2v2\fP, \f2v3\fP) Sets the color used to draw the lines and borders around shapes .PD .TP \f5noStroke() Disable shapes outline .TP \f5color(\f2v1\fP, \f2v2\fP, \f2v3\fP) Creates a color object which is an lua table with r, g, and b fields. The parameters are affected by the current color mode, meaning they will be interpreted as either RGB or HSB. .TP \f5lerpColor(\f2c1\fP, \f2c2\fP, \f2amt\fP) Compute a .I color by interpolating colors .I c1 and .I c2 linearly by .I amt \&. .SS Image .TP \f5pixels[] The .I pixels[] array gives direct access to the canvas pixels. .I pixels[] is an array of size .I width x height where each individual element is a color object obtained with the .I color function. Before accessing the array, the data must be loaded using the .I loadPixels() functions. To reflect the changes to the .I pixels[] array, the function .I updatePixels() must be called. Accessing the array without these calls will have no effect on the canvas image. .TP \f5loadPixels() Loads the canvas image pixels into the .I pixels[] array. .TP \f5updatePixels() Update the canvas image content with the data in the .I pixels[] array. .SS Shape .TP \f5arc(\f2x\fP, \f2y\fP, \f2width\fP, \f2height\fP, \f2start\fP, \f2stop\fP) Arc draws an arc centered on point .I (x,y) using an horizontal radius of size .I width and a vertical radius of size .I height .TP \f5circle(\f2x\fP, \f2y\fP, \f2radius\fP) Draws a circle centered on point .I (x,y) with a radius of size .I radius .TP \f5ellipse(\f2x\fP, \f2y\fP, \f2a\fP, \f2b\fP) Draws an ellipse centered on point .I (x,y) with an horizontal radius of size .I a and a vertical radius of size .I b .TP \f5line(\f2x1\fP, \f2y1\fP, \f2x2\fP, \f2y2\fP) Draws a line between points .I (x1,y1) and .I (x2,y2) .TP \f5point(\f2x\fP, \f2y\fP) Draws a point at .I (x,y) .TP \f5square(\f2x\fP, \f2y\fP, \f2a\fP) Draws a square on the canvas. The top-left corner of the square is set at point .I (x,y) The length of the sides is defined by the .I a parameter .TP \f5rect(\f2x\fP, \f2y\fP, \f2w\fP, \f2h\fP) Draws a rectangle on the canvas. The left-left corner of the rectanglee is set at point .I (x,y) The width and height of the rectangle are defined by the .I w and .I h parameters. .TP \f5quad(\f2x1\fP, \f2y1\fP, \f2x2\fP, \f2y2\fP, \f2x3\fP, \f2y3\fP, \f2x4\fP, \f2y4\fP) Draws a quadrilateral (i.e. a four-sided polygon) .TP \f5triangle(\f2x1\fP, \f2y1\fP, \f2x2\fP, \f2y2\fP, \f2x3\fP, \f2y3\fP) Draws a triangle .TP \f5bezier(\f2x1\fP, \f2y1\fP, \f2x2\fP, \f2y2\fP, \f2x3\fP, \f2y3\fP, \f2x4\fP, \f2y4\fP) Draws a cubic Bezier curve defined by the points .I (x1,y1) .I (x2,y2) .I (x3,y3) .I (x4,y4) .SS Attributes The following functions control the attributes of shapes drawing. .TP \f5strokeWeight(\f2w\fP) Sets the width of the stroke used for points, lines and border around shapes. .TP \f5strokeCap(\f2a\fP) Sets the style of rendering for line endings. The .I a parameter can be either .I SQUARE which is the default or .I ROUND .SS Transform .TP \f5translate(\f2x\fP, \f2y\fP) Specifies the displacement of points in the canvas. The .x parameter specifies the horizontal translation, the .y parameter specifies the vertical one. .PD 0 .TP .B NB: Transformations are cumulative which means that subsequent calls to .IR translate accumulates the translation. .PD .TP \f5rotate(\f2angle\fP) Specifies the angle by which shapes are rotated when drawn on canvas. The .I angle parameter is expressed in radians (it can be converted from degrees by using the .IR radians() function). .PD 0 .TP .B NB: Transformations are cumulative which means that subsequent calls to .IR rotate increase the rotation. .PD .TP \f5pushMatrix() Pushes the current transformation matrix onto the matrix stack. This saves the current coordinate system (translations and rotations) on the stack and allows to control the scope of transformations. .PD .TP \f5popMatrix() Pops the transformation matrix off the stack. This restores the coordinate system to its state before the last call to .I pushMatrix .SS Environment .TP \f5pushStyle() Saves all style related settings ( .IR strokeWeight , .IR strokeCap , \&... ). .TP \f5popStyle() Restores all style related settings previously saved by a call to .IR pushStyle \&. .TP \f5push() Convenient helper that saves both the style settings and the transformation matrix. .TP \f5pop() Restore style settings and transformation matrix previously saved by a call to .IR push \&. .TP \f5width Global variable set to the .IR width of the canvas. .TP \f5height Global variable set to the .IR height of the canvas. .TP \f5size(\f2width\fP, \f2height\fP) Sets the size of the .IR slug canvas to .I width x .I height \&. .I size can only be used from the .IR setup function and will have no effect if called from .IR draw \&. .TP \f5frameRate(\f2v\fP) Sets the number of frames per seconds for the draw loop. By default .IR slug uses 90 FPS. .SS Input .TP \f5mouseX Global variable containing the horizontal coordinate of the mouse. .TP \f5mouseY Global variable containing the vertical coordinate of the mouse. .SS Math Following functions extend the standard lua .I math library. .TP \f5math.dist(\f2x1\fP, \f2y1\fP, \f2x2\fP, \f2y2\fP) Computes the distance between points .I (x1,y1) and .I (x2, y2) \&. .TP \f5math.map(\f2x\fP, \f2y\fP) Computes the magnitude of the vector .I (x,y) \&. This is equivalent to the distance of point .I (x,y) to the origin .I (0,0) .TP \f5math.constrain(\f2v\fP, \f2min\fP, \f2max\fP) Constrains the value .I v to the range .I [min;max] \&. .TP \f5math.map(\f2v\fP, \f2s1\fP, \f2e1\fP, \f2s2\fP, \f2e2\fP) Maps the number .I v from the range .I [s1;e1] to the range .I [s2;e2] \&. Note that the result is not constrained to the target range which, if needed, can be achieved by a call to .IR constrain() \&. .TP \f5math.norm(\f2v\fP, \f2s\fP, \f2e\fP) Normalizes the value .I v from range .I [s;e] to a value in the range .I [0;1] \&. This is equivalent to: .I math.map(v, s, e, 0.0, 1.0) \&. .TP \f5math.lerp(\f2a\fP, \f2b\fP, \f2r\fP) Computes a linear interpolation between numbers .I a and .I b using an interpolation value of .I r \&. .TP \f5math.randomGaussian() .PD 0 .TP \f5math.randomGaussian(\f2mean\fP) .PD 0 .TP \f5math.randomGaussian(\f2mean\fP, \f2stddev\fP) Returns a random number fitting a Gaussian (or normal) distribution. The arguments are the mean and the standard deviation which defaults to 0.0 and 1.0 respectively. .SH AUTHOR phil9 .SH LICENSE MIT