OSCII-bot code reference

Generated by OSCII-bot v0.6

Scripts use lines beginning with @ to specify various parameters:Special variables: The code for OSCII-bot is written in a simple language (called EEL2), which has many similarities to C. Code is written in one or more of the code sections listed above. Some basic features of this language are:

Operator reference

Listed from highest precedence to lowest (but one should use parentheses whenever there is doubt!):

Some key notes about the above, especially for C programmers:

Strings

Strings can be specified as literals using quotes, such as "This is a test string". Much of the syntax mirrors that of C: you must escape quotes with backslashes to put them in strings ("He said \"hello, world\" to me"), multiple literal strings will be automatically concatenated by the compiler. Unlike C, quotes can span multiple lines. There is a soft limit on the size of each string: attempts to grow a string past about 16KB will result in the string not being modified.

Strings are always refered to by a number, so one can reference a string using a normal JS variable:
    x = "hello world";
    gfx_drawstr(x);
Literal strings are mutable in OSCII-bot, and you can also have other named strings:



Function List

while     memcpy     strlen     eval     gfx_init     gfx_printf    
loop     memset     strcpy     tcp_listen     gfx_quit     gfx_blurto    
sin     mem_get_values     strcat     tcp_listen_end     gfx_aaaaa     gfx_blit    
cos     mem_set_values     strcmp     tcp_connect     gfx_getchar     gfx_blit    
tan     stack_push     stricmp     tcp_send     gfx_showmenu     gfx_blitext    
sqrt     stack_pop     strncmp     tcp_recv     gfx_setcursor     gfx_getimgdim    
log     stack_peek     strnicmp     tcp_set_block     gfx_lineto     gfx_setimgdim    
log10     stack_exch     strncpy     tcp_close     gfx_line     gfx_loadimg    
asin     rand     strncat     fopen     gfx_rectto     gfx_gradrect    
acos     midisend     strcpy_from     fclose     gfx_rect     gfx_muladdrect    
atan     midisend_str     strcpy_substr     fread     gfx_setpixel     gfx_deltablit    
atan2     oscsend     str_getchar     fgets     gfx_getpixel     gfx_transformblit    
exp     oscmatch     str_setchar     fgetc     gfx_drawnumber     gfx_circle    
abs     oscparm     str_setlen     fwrite     gfx_drawchar     gfx_triangle    
sqr     get_device_open_time     str_delsub     fprintf     gfx_drawstr     gfx_roundrect    
min     printf     str_insert     fseek     gfx_measurestr     gfx_arc    
max     sprintf     sleep     ftell     gfx_measurechar     gfx_set    
sign     matchi     time     feof     gfx_setfont     gfx_clienttoscreen    
floor     match     time_precise     fflush     gfx_getfont     gfx_screentoclient    
ceil     strlen     eval    




while(expression)

Executes expression until expression evaluates to zero, or until 1048576iterations occur. An alternate and more useful syntax is while (expression) ( statements ), which evaluates statements after every non-zero evaluation of expression.



loop(count,expression)

Evaluates count once, and then executes expression count, but not more than 1048576, times.



sin(angle)

Returns the sine of the angle specified (specified in radians -- to convert from degrees to radians, multiply by $pi/180, or 0.017453).



cos(angle)

Returns the cosine of the angle specified (specified in radians).



tan(angle)

Returns the tangent of the angle specified (specified in radians).



sqrt(value)

Returns the square root of the parameter. If the parameter is negative, the return value is undefined.



log(value)

Returns the natural logarithm (base e) of the parameter. If the value is not greater than 0, the return value is undefined.



log10(value)

Returns the base-10 logarithm of the parameter. If the value is not greater than 0, the return value is undefined.



asin(value)

Returns the arc sine of the value specified (return value is in radians). If the parameter is not between -1.0 and 1.0 inclusive, the return value is undefined.



acos(value)

Returns the arc cosine of the value specified (return value is in radians). If the parameter is not between -1.0 and 1.0 inclusive, the return value is undefined.



atan(value)

Returns the arc tangent of the value specified (return value is in radians). If the parameter is not between -1.0 and 1.0 inclusive, the return value is undefined.



atan2(numerator,denominator)

Returns the arc tangent of the numerator divided by the denominator, allowing the denominator to be 0, and using their signs to produce a more meaningful result.



exp(exponent)

Returns the number e ($e, approximately 2.718) raised to the parameter-th power. This function is significantly faster than pow() or the ^ operator.



abs(value)

Returns the absolute value of the parameter.



sqr(value)

Returns the square of the parameter (similar to value*value, but only evaluating value once).



min(&value,&value)

Returns (by reference) the minimum value of the two parameters. Since min() returns by reference, expressions such as min(x,y) = 5 are possible.



max(&value,&value)

Returns (by reference) the maximum value of the two parameters. Since max() returns by reference, expressions such as max(x,y) = 5 are possible.



sign(value)

Returns 1.0 if the parameter is greater than 0, -1.0 if the parameter is less than 0, or 0 if the parameter is 0.



floor(value)

Returns the value rounded to the next lowest integer (floor(3.9)==3, floor(-3.1)==-4).



ceil(value)

Returns the value rounded to the next highest integer (ceil(3.1)==4, ceil(-3.9)==-3).



invsqrt(value)

Returns a fast inverse square root (1/sqrt(x)) approximation of the parameter.



freembuf(address)

Hints the runtime that memory above the address specified may no longer be used. The runtime may, at its leisure, choose to lose the contents of memory above the address specified.



memcpy(dest,src,length)

Copies length items of memory from src to dest. Regions are permitted to overlap.



memset(offset,value,length)

Sets length items of memory at offset to value.



mem_get_values(offset, ...)

Reads values from memory starting at offset into variables specified. Slower than regular memory reads for less than a few variables, faster for more than a few. Undefined behavior if used with more than 32767 variables.



mem_set_values(offset, ...)

Writes values to memory starting at offset from variables specified. Slower than regular memory writes for less than a few variables, faster for more than a few. Undefined behavior if used with more than 32767 variables.



stack_push(&value)

Pushes value onto the user stack, returns a reference to the parameter.



stack_pop(&value)

Pops a value from the user stack into value, or into a temporary buffer if value is not specified, and returns a reference to where the stack was popped. Note that no checking is done to determine if the stack is empty, and as such stack_pop() will never fail.



stack_peek(index)

Returns a reference to the item on the top of the stack (if index is 0), or to the Nth item on the stack if index is greater than 0.



stack_exch(&value)

Exchanges a value with the top of the stack, and returns a reference to the parameter (with the new value).



rand([max])

Returns a psuedorandom real number between 0 and the parameter, inclusive. If the parameter is omitted or less than 1.0, 1.0 is used as a maximum instead.



midisend(device_index)

Sends a MIDI event (specified by variables msg1,msg2,msg3) to the device specified by device_index.

device_index can be -100 to send to all outputs opened by application, -1 to send to all outputs opened by script.



midisend_str(device_index,"string")

(v0.5+) Sends a MIDI event (specified by the contents of a string) to the device specified by device_index.

device_index can be -100 to send to all outputs opened by application, -1 to send to all outputs opened by script. Can be used to send SysEx, for example: midisend_str(midiout, "\xF0\x00\x01\x02\xF7").



oscsend(device_index,"string"[,value,...])

Sends an OSC event (specified by "string" and one or more parameters specifying values) to device specified by device_index.

device_index can be -100 to send to all outputs opened by application, -1 to send to all outputs opened by script.

"string" is OSC message, and can have a prefix specifying type and count of values.

Additional parameters (after values) will be used as parameters to any format specifiers in "string".

Prefixes are one or more characters of 'f' (float), 'i' (integer), 'b' (bool), 's' (string), which specify an OSC value of that type.



oscmatch("string"[,format-output])

Matches the current OSC event against "string" (see match()), and puts any matched specifiers (%s, %d, etc) into parameters specified (or fmt0..fmtX if not specified).

oscmatch() is the equivalent of match("string",oscstr)



oscparm(parm_idx[,type,#string])

Gets the parameter value for the current OSC message.

If type is specified, it will be set to the type of the parameter ('f', 's', etc).

If #string is specified and type is 's', #string will be set to the OSC parameter string.



get_device_open_time(device_index)

Returns the timestamp (similar to time_precise()) of the last time this device was opened/re-opened, can be used to detect device reconnection.



printf("format"[, ...])

Output formatted string to system-specific destination, see sprintf() for more information



sprintf(#dest,"format"[, ...])

Formats a string and stores it in #dest. Format specifiers begin with %, and may include:
Many standard C printf() modifiers can be used, including:
Values for format specifiers can be specified as additional parameters to sprintf, or within {} in the format specifier (such as %{varname}d, in that case a global variable is always used).



matchi("needle","haystack"[, ...])

Case-insensitive version of match().



match("needle","haystack"[, ...])

Searches for the first parameter in the second parameter, using a simplified regular expression syntax.
You can also use format specifiers to match certain types of data, and optionally put that into a variable:
See also sprintf() for other notes, including specifying direct variable references via {}.



strlen("str")

Returns the length of the string passed as a parameter



strcpy(#str,"srcstr")

Copies the contents of srcstr to #str, and returns #str



strcat(#str,"srcstr")

Appends srcstr to #str, and returns #str



strcmp("str","str2")

Compares strings, returning 0 if equal



stricmp("str","str2")

Compares strings ignoring case, returning 0 if equal



strncmp("str","str2",maxlen)

Compares strings giving up after maxlen characters, returning 0 if equal



strnicmp("str","str2",maxlen)

Compares strings giving up after maxlen characters, ignoring case, returning 0 if equal



strncpy(#str,"srcstr",maxlen)

Copies srcstr to #str, stopping after maxlen characters. Returns #str.



strncat(#str,"srcstr",maxlen)

Appends srcstr to #str, stopping after maxlen characters of srcstr. Returns #str.



strcpy_from(#str,"srcstr",offset)

Copies srcstr to #str, but starts reading srcstr at offset offset



strcpy_substr(#str,"srcstr",offs,ml))

PHP-style (start at offs, offs<0 means from end, ml for maxlen, ml<0 = reduce length by this amt)



str_getchar("str",offset[,type])

Returns the data at byte-offset offset of str. If offset is negative, position is relative to end of string.type defaults to signed char, but can be specified to read raw binary data in other formats (note the single quotes, these are single/multi-byte characters):



str_setchar(#str,offset,val[,type]))

Sets value at offset offset, type optional. offset may be negative to refer to offset relative to end of string, or between 0 and length, inclusive, and if set to length it will lengthen string. see str_getchar() for more information on types.



str_setlen(#str,len)

Sets length of #str (if increasing, will be space-padded), and returns #str.



str_delsub(#str,pos,len)

Deletes len characters at offset pos from #str, and returns #str.



str_insert(#str,"srcstr",pos)

Inserts srcstr into #str at offset pos. Returns #str



sleep(ms)

Yields the CPU for the millisecond count specified, calling Sleep() on Windows or usleep() on other platforms.



time([&val])

Sets the parameter (or a temporary buffer if omitted) to the number of seconds since January 1, 1970, and returns a reference to that value. The granularity of the value returned is 1 second.



time_precise([&val])

Sets the parameter (or a temporary buffer if omitted) to a system-local timestamp in seconds, and returns a reference to that value. The granularity of the value returned is system defined (but generally significantly smaller than one second).



eval("code")

Executes code passed in. Code can use functions, but functions created in code can't be used elsewhere.



tcp_listen(port[,"interface",#ip_out])

Listens on port specified. Returns less than 0 if could not listen, 0 if no new connection available, or greater than 0 (as a TCP connection ID) if a new connection was made. If a connection made and #ip_out specified, it will be set to the remote IP. interface can be empty for all interfaces, otherwise an interface IP as a string.



tcp_listen_end(port)

Ends listening on port specified.



tcp_connect("address",port[,block])

Create a new TCP connection to address:port. If block is specified and 0, connection will be made nonblocking. Returns TCP connection ID greater than 0 on success.



tcp_send(connection,"str"[,len])

Sends a string to connection. Returns -1 on error, 0 if connection is non-blocking and would block, otherwise returns length sent. If len is specified and not less than 1, only the first len bytes of the string parameter will be sent.



tcp_recv(connection,#str[,maxlen])

Receives data from a connection to #str. If maxlen is specified, no more than maxlen bytes will be received. If non-blocking, 0 will be returned if would block. Returns less than 0 if error.



tcp_set_block(connection,block)

Sets whether a connection blocks.



tcp_close(connection)

Closes a TCP connection created by tcp_listen() or tcp_connect().



fopen("fn","mode")

Opens a file "fn" with mode "mode". For read, use "r" or "rb", write "w" or "wb". Returns a positive integer on success.



fclose(fp)

Closes a file previously opened with fopen().



fread(fp,#str,length)

Reads from file fp into #str, up to length bytes. Returns actual length read, or negative if error.



fgets(fp,#str)

Reads a line from file fp into #str. Returns length of #str read.



fgetc(fp)

Reads a character from file fp, returns -1 if EOF.



fwrite(fp,#str,len)

Writes up to len characters of #str to file fp. If len is less than 1, the full contents of #str will be written. Returns the number of bytes written to file.



fprintf(fp,"format"[,...])

Formats a string and writes it to file fp. For more information on format specifiers, see sprintf(). Returns bytes written to file.



fseek(fp,offset,whence)

Seeks file fp, offset bytes from whence reference. Whence negative specifies start of file, positive whence specifies end of file, and zero whence specifies current file position.



ftell(fp)

Retunrs the current file position.



feof(fp)

Returns nonzero if the file fp is at the end of file.



fflush(fp)

If file fp is open for writing, flushes out any buffered data to disk.



gfx_init("name"[,width,height,xpos,ypos])

Initializes the graphics window with title name. Suggested width and height can be specified.

Once the graphics window is open, gfx_update() should be called periodically.



gfx_quit()

Closes the graphics window.



gfx_aaaaa()

The following global variables are special and will be used by the graphics system:





gfx_getchar([char])

If char is 0 or omitted, returns a character from the keyboard queue, or 0 if no character is available, or -1 if the graphics window is not open. If char is specified and nonzero, that character's status will be checked, and the function will return greater than 0 if it is pressed.

Common values are standard ASCII, such as 'a', 'A', '=' and '1', but for many keys multi-byte values are used, including 'home', 'up', 'down', 'left', 'rght', 'f1'.. 'f12', 'pgup', 'pgdn', 'ins', and 'del'.

Modified and special keys can also be returned, including:



gfx_showmenu("str")

Shows a popup menu at gfx_x,gfx_y. str is a list of fields separated by | characters. Each field represents a menu item.
Fields can start with special characters:

# : grayed out
! : checked
> : this menu item shows a submenu
< : last item in the current submenu

An empty field will appear as a separator in the menu. gfx_showmenu returns 0 if the user selected nothing from the menu, 1 if the first field is selected, etc.
Example:

gfx_showmenu("first item, followed by separator||!second item, checked|>third item which spawns a submenu|#first item in submenu, grayed out|<second and last item in submenu|fourth item in top menu")



gfx_setcursor(resource_id)

Sets the mouse cursor. resource_id is a value like 32512 (for an arrow cursor).



gfx_lineto(x,y[,aa])

Draws a line from gfx_x,gfx_y to x,y. If aa is 0.5 or greater, then antialiasing is used. Updates gfx_x and gfx_y to x,y.



gfx_line(x,y,x2,y2[,aa])

Draws a line from x,y to x2,y2, and if aa is not specified or 0.5 or greater, it will be antialiased.



gfx_rectto(x,y)

Fills a rectangle from gfx_x,gfx_y to x,y. Updates gfx_x,gfx_y to x,y.



gfx_rect(x,y,w,h[,filled])

Fills a rectangle at x,y, w,h pixels in dimension, filled by default.



gfx_setpixel(r,g,b)

Writes a pixel of r,g,b to gfx_x,gfx_y.



gfx_getpixel(r,g,b)

Gets the value of the pixel at gfx_x,gfx_y into r,g,b.



gfx_drawnumber(n,ndigits)

Draws the number n with ndigits of precision to gfx_x, gfx_y, and updates gfx_x to the right side of the drawing. The text height is gfx_texth.



gfx_drawchar(char)

Draws the character (can be a numeric ASCII code as well), to gfx_x, gfx_y, and moves gfx_x over by the size of the character.



gfx_drawstr("str"[,flags,right,bottom])

Draws a string at gfx_x, gfx_y, and updates gfx_x/gfx_y so that subsequent draws will occur in a similar place.

If flags, right ,bottom passed in:
  • flags&1: center horizontally
  • flags&2: right justify
  • flags&4: center vertically
  • flags&8: bottom justify
  • flags&256: ignore right/bottom, otherwise text is clipped to (gfx_x, gfx_y, right, bottom)



    gfx_measurestr("str",&w,&h)

    Measures the drawing dimensions of a string with the current font (as set by gfx_setfont).



    gfx_measurechar(character,&w,&h)

    Measures the drawing dimensions of a character with the current font (as set by gfx_setfont).



    gfx_setfont(idx[,"fontface", sz, flags])

    Can select a font and optionally configure it. idx=0 for default bitmapped font, no configuration is possible for this font. idx=1..16 for a configurable font, specify fontface such as "Arial", sz of 8-100, and optionally specify flags, which is a multibyte character, which can include 'i' for italics, 'u' for underline, or 'b' for bold. These flags may or may not be supported depending on the font and OS. After calling gfx_setfont(), gfx_texth may be updated to reflect the new average line height.



    gfx_getfont([#str])

    Returns current font index. If a string is passed, it will receive the actual font face used by this font, if available.



    gfx_printf("format"[, ...])

    Formats and draws a string at gfx_x, gfx_y, and updates gfx_x/gfx_y accordingly (the latter only if the formatted string contains newline). For more information on format strings, see sprintf()



    gfx_blurto(x,y)

    Blurs the region of the screen between gfx_x,gfx_y and x,y, and updates gfx_x,gfx_y to x,y.



    gfx_blit(source,scale,rotation)

    If three parameters are specified, copies the entirity of the source bitmap to gfx_x,gfx_y using current opacity and copy mode (set with gfx_a, gfx_mode). You can specify scale (1.0 is unscaled) and rotation (0.0 is not rotated, angles are in radians).
    For the "source" parameter specify -1 to use the main framebuffer as source, or an image index (see gfx_loadimg()).



    gfx_blit(source, scale, rotation[, srcx, srcy, srcw, srch, destx, desty, destw, desth, rotxoffs, rotyoffs])

    srcx/srcy/srcw/srch specify the source rectangle (if omitted srcw/srch default to image size), destx/desty/destw/desth specify dest rectangle (if not specified, these will default to reasonable defaults -- destw/desth default to srcw/srch * scale).



    gfx_blitext(source,coordinatelist,rotation)

    Deprecated, use gfx_blit instead.



    gfx_getimgdim(image,w,h)

    Retreives the dimensions of image (representing a filename: index number) into w and h. Sets these values to 0 if an image failed loading (or if the filename index is invalid).



    gfx_setimgdim(image,w,h)

    Resize image referenced by index 0..127, width and height must be 0-2048. The contents of the image will be undefined after the resize.



    gfx_loadimg(image,"filename")

    Load image from filename into slot 0..127 specified by image. Returns the image index if success, otherwise -1 if failure. The image will be resized to the dimensions of the image file.



    gfx_gradrect(x,y,w,h, r,g,b,a[, drdx, dgdx, dbdx, dadx, drdy, dgdy, dbdy, dady])

    Fills a gradient rectangle with the color and alpha specified. drdx-dadx reflect the adjustment (per-pixel) applied for each pixel moved to the right, drdy-dady are the adjustment applied for each pixel moved toward the bottom. Normally drdx=adjustamount/w, drdy=adjustamount/h, etc.



    gfx_muladdrect(x,y,w,h,mul_r,mul_g,mul_b[,mul_a,add_r,add_g,add_b,add_a])

    Multiplies each pixel by mul_* and adds add_*, and updates in-place. Useful for changing brightness/contrast, or other effects.



    gfx_deltablit(srcimg,srcx,srcy,srcw,srch,destx,desty,destw,desth,dsdx,dtdx,dsdy,dtdy,dsdxdy,dtdxdy)

    Blits from srcimg(srcx,srcy,srcw,srch) to destination (destx,desty,destw,desth). Source texture coordinates are s/t, dsdx represents the change in s coordinate for each x pixel, dtdy represents the change in t coordinate for each y pixel, etc. dsdxdy represents the change in dsdx for each line.



    gfx_transformblit(srcimg,destx,desty,destw,desth,div_w,div_h,table)

    Blits to destination at (destx,desty), size (destw,desth). div_w and div_h should be 2..64, and table should point to a table of 2*div_w*div_h values (this table must not cross a 65536 item boundary). Each pair in the table represents a S,T coordinate in the source image, and the table is treated as a left-right, top-bottom list of texture coordinates, which will then be rendered to the destination.



    gfx_circle(x,y,r[,fill,antialias])

    Draws a circle, optionally filling/antialiasing.



    gfx_triangle(x1,y1,x2,y2,x3,y3[x4,y4...])

    Draws a filled triangle, or any convex polygon.



    gfx_roundrect(x,y,w,h,radius[,antialias])

    Draws a rectangle with rounded corners.



    gfx_arc(x,y,r,ang1,ang2[,antialias])

    Draws an arc of the circle centered at x,y, with ang1/ang2 being specified in radians.



    gfx_set(r[,g,b,a,mode,dest])

    Sets gfx_r/gfx_g/gfx_b/gfx_a/gfx_mode, sets gfx_dest if final parameter specified



    gfx_clienttoscreen(x,y)

    Converts client coordinates x,y to screen coordinates.



    gfx_screentoclient(x,y)

    Converts screen coordinates x,y to client coordinates.