Pixilang User Manual
PDF version of this page
Русская версия

What is Pixilang

Pixilang is a pixel-oriented programming language for small graphics/sound applications and experiments: demos, games, synths, etc.

Pixilang programs are stored in text files (UTF-8 encoding) with extensions .txt or .pixi. So you can use your favorite text editor to create/edit these files. Pixilang has no built-in editor.

A program can be a simple list of instructions with conditional jumps, without declaring entry points and functions. A blank area (screen) inside the Pixilang window is provided for any program. The screen can be accessed as an array of pixels.

Command line options

pixilang [options] [filename] [arg] Options: -? show help clearall reset all settings -cfg <config> apply additional configuration in the following format: "OPTION1=VALUE|OPTION2=VALUE|..." -c generate bytecode; filename.pixicode file will be produced Filename: source (UTF-8 text file) or bytecode (*.pixicode). Additional arguments (arg): some options for the Pixilang program.

Basics

The basis of the Pixilang - containers and variables.

Container is a two-dimensional array of elements (numbers) of the same data type. Different containers may have different data types. Each container has its own unique ID number. ID is always a positive integer or zero: 0,1,2,3,4... Zero ID is ok, but it's the screen container number by default.

Container structure:

  • two-dimensional table of container elements - it may be some image, text string, piece of audio, or other data;
  • key color, which will be treated as transparent color (with alpha=0);
  • reference to a container with alpha-channel;
  • additional data:
    • properties (use get_prop(), set_prop(), remove_prop, remove_props(), or a . (dot) operator to access them);
    • animation (use Animation functions to access it).

The new container can be created with the new() function or returned by some other function. There are two ways to remove the container:
  • by user through the remove() function;
  • automatically after the end of the program.
There is no automatic garbage collector.

Maximum number of containers is 8192. But you can increase it using the parameter pixi_containers_num in pixilang_config.ini. Also you can change this number in the user_code_info.cpp (if you compile Pixilang from source) through the following code:app_option g_app_options[] = { { "pixi_containers_num", 16384 }, { NULL } };

Variable can contain 32-bit signed integer or 32-bit floating point number.

Numbers can be described in different formats. Examples:

  • 33 - decimal;
  • 33.55 - decimal floating point;
  • 0xA8BC - hexadecimal;
  • 0b100101011 - binary;
  • #FF9080 - color, as in HTML; base format is #RRGGBB, where RR - red intensity (from 00 to FF), GG - green intensity; BB - blue intensity; the actual color format (bit arrangement in the value) depends on the system, so always use form #RRGGBB or get_color(R,G,B) to get the correct color value.

Examplesx = new( 4 ) //Create a new container with 4 pixels. Store its ID into the variable x. //Container elements are addressed from zero: // first element - x[ 0 ]; // second element - x[ 1 ]; // ... // last element - x[ container_size - 1 ] x[ 0 ] = #0000FF //Assign blue color to the first pixel of container x. x[ 2 ] = WHITE //Assign white color to pixel 2. x[ 3 ] = RED //Assign red color to pixel 3 (last element). x[ 4 ] = BLUE //Nothing will happen here because index 4 is out of range. b = x[ 2 ] //Read an element with index 2. //Here b contains the number corresponding to the white color. c = x[ 8 ] //Try to read an element with index 8 //Here c contains a null value because index 8 is not available. remove( x ) //Remove the containerc = new( 4, 4 ) //Create a new 2D 4x4 pixel container. Store its ID into the variable x. c[ 2, 2 ] = WHITE //Assign the white color to a pixel with coordinates x=2 y=2. remove( c ) //Remove this containerstr = "Hello" //"Hello" is the string container with five 8-bit characters (UTF-8 encoding). //This container is automatically created during the bytecode generation. //You don't need to delete it manually. str[ 0 ] = 'h' //Change the first character from 'H' to 'h'. print( str, 0, 0 ) //will print the word "hello" on the screen //The string can be terminated with a null character or the end of a container. str[ 2 ] = 0 //Replace the char 'l' with a zero print( str, 0, 8 ) //will print the word "he" on the screena = 4 //Global variable fn function() { $k = 2 //Local variable function2 = { //Body of another function $x = 899.334 //Local variable //$k is not accessible here } //$x is not accessible here } //$k and $x are not accessible here

Coordinate system of the Pixilang is described on the following image:

Paths and file names

//File is in the same folder with the pixi-program: "filename" //File is in the current working directory: // Linux/Windows/OSX: in the same folder with Pixilang; // iOS: documents; // WinCE: root of local filesystem (/); "1:/filename" //File is in the user directory for configs and caches : // Linux: /home/username/.config/Pixilang; // iOS: directory with application support files (NSApplicationSupportDirectory); // Android: internal files directory; "2:/filename" //File is in the temporary directory: "3:/filename"

Operators

//if, else if a == b { /*This code is executed if a equals b*/ } else { /*This code is executed otherwise*/ } if x == 4 && y == 2 { /*This code is executed if x equals 4 and y equals 2*/ } //while a = 0 while( a < 3 ) { //This code is executed while a less than 3 a + 3 } //while + break a = 0 while( a < 100 ) { if a == 10 { break } //If a = 10, break the loop //Use breakX operator to break X nested loops. Example: break2 //Use breakall operator to break all current active loops a + 1 } //while + continue a = 0 b = 0 while( a < 100 ) { if a == 10 { a + 1 continue } //If a = 10, go to the next loop iteration // (ignore the next two lines of code) a + 1 b + 1 } //go, goto m1: a + 1 goto m1 //Go to the m1 label //halt, stop halt //Stop the program here //include include "prog2.txt" //Include code from prog2.txt //fn fn fff( $x, $y ) //Declare function fff with parameters $x and $y { //Function fff body ret //Simple return from the function ret( 4 ) //Return with value 4 }

The following table lists the mathematical operators. Priority 0 - the highest, such operations will be executed first.

PriorityOperatorDescriptionResultExample
0%Modulo (remainder)Integera = b % 4
0/DivisionFloating pointa = b / 4
0divInteger divisionIntegera = b div 4
0*MultiplicationDepends on the operandsa = b * 4
0!Logical NOTInteger 1 or 0if !condition { ... }
0~Bitwise NOT (inversion)Integera = ~b
1+AdditionDepends on the operandsa = b + 4
1-SubtractionDepends on the operandsa = b - 4
2>>Bitwise right shiftIntegera = b >> 4
2<<Bitwise left shiftIntegera = b << 4
3==Equal toInteger 1 or 0if a == b {}
3!=Not equal toInteger 1 or 0if a != b {}
3<Less thanInteger 1 or 0if a < b {}
3>Greater thanInteger 1 or 0if a > b {}
3<=Less than or equal toInteger 1 or 0if a <= b {}
3>=Greater than or equal toInteger 1 or 0if a >= b {}
4|Bitwise ORIntegera = b | 4
4^Bitwise XORIntegera = b ^ 4
4&Bitwise ANDIntegera = b & 4
5||Logical ORInteger 1 or 0if a || b {}
5&&Logical ANDInteger 1 or 0if a && b {}

Built-in constants

Container types

64-bit types are not supported by default. But they can be enabled in pixilang.h for the custom build of Pixilang.

  • INT - signed integer (size depends on the version of Pixilang);
  • INT8 - signed integer (8 bit); range: -128 to 127;
  • INT16 - signed integer (16 bit); range: -32768 to 32767;
  • INT32 - signed integer (32 bit); range: -2147483648 to 2147483647;
  • INT64 - signed integer (64 bit);
  • FLOAT - floating point (size depends on the version of Pixilang);
  • FLOAT32 - floating point (32 bit);
  • FLOAT64 - floating point (64 bit);
  • PIXEL - pixel in native color format; will be converted to type INTx, where x - number of bits per pixel.

Container flags

  • CFLAG_INTERP - enable software interpolation.

For OpenGL acceleration:
  • GL_MIN_LINEAR;
  • GL_MAG_LINEAR;
  • GL_NICEST - use 32bit color, when possible;
  • GL_NO_XREPEAT;
  • GL_NO_YREPEAT;
  • GL_NO_ALPHA.

Container resizing flags

  • RESIZE_INTERP1 - rough resizing;
  • RESIZE_INTERP2 - resize with linear interpolation;
  • RESIZE_UNSIGNED_INTERP2;
  • RESIZE_COLOR_INTERP1;
  • RESIZE_COLOR_INTERP2.

Container copying flags

  • COPY_NO_AUTOROTATE - don't rotate pixels from GL_SCREEN;
  • COPY_CLIPPING - check and limit the values, if the type of the source container differs from the destination.

ZLib

Compression levels:

  • Z_NO_COMPRESSION;
  • Z_BEST_SPEED;
  • Z_BEST_COMPRESSION;
  • Z_DEFAULT_COMPRESSION.

File formats

R - reading is supported; W - writing is supported.

  • FORMAT_RAW - raw data without a header (RW);
  • FORMAT_WAVE (RW);
  • FORMAT_AIFF (R);
  • FORMAT_OGG;
  • FORMAT_MP3;
  • FORMAT_FLAC;
  • FORMAT_MIDI (R);
  • FORMAT_SUNVOX (RW);
  • FORMAT_SUNVOXMODULE (R);
  • FORMAT_XM (R);
  • FORMAT_MOD (R);
  • FORMAT_JPEG (RW);
  • FORMAT_PNG (RW);
  • FORMAT_GIF (RW);
  • FORMAT_AVI;
  • FORMAT_MP4;
  • FORMAT_ZIP;
  • FORMAT_PIXICONTAINER - entire Pixilang container with properties and animation (RW).

Load/Save options

  • LOAD_FIRST_FRAME - load first frame only.

GIF saving:
  • GIF_GRAYSCALE;
  • GIF_DITHER.

JPEG saving:
  • JPEG_H1V1 - YCbCr, no subsampling (H1V1, YCbCr 1x1x1, 3 blocks per MCU);
  • JPEG_H2V1 - YCbCr, H2V1 subsampling (YCbCr 2x1x1, 4 blocks per MCU);
  • JPEG_H2V2 - YCbCr, H2V2 subsampling (YCbCr 4x1x1, 6 blocks per MCU); default;
  • JPEG_TWOPASS - number of passes = 2.

Colors

  • ORANGE;
  • BLACK;
  • WHITE;
  • YELLOW;
  • RED;
  • GREEN;
  • BLUE;

Alignment

  • TOP;
  • BOTTOM;
  • LEFT;
  • RIGHT.

Effects

Effect types for effector() function:

  • EFF_NOISE - noise;
  • EFF_SPREAD_LEFT - random pixel shift to the left;
  • EFF_SPREAD_RIGHT - random pixel shift to the right;
  • EFF_SPREAD_UP - random pixel shift to the top;
  • EFF_SPREAD_DOWN - random pixel shift to the bottom;
  • EFF_HBLUR - horizontal blur;
  • EFF_VBLUR - vertical blur;
  • EFF_COLOR - color fill.

OpenGL

gl_draw_arrays() (analog of the glDrawArrays()) modes:

  • GL_POINTS;
  • GL_LINE_STRIP;
  • GL_LINE_LOOP;
  • GL_LINES;
  • GL_TRIANGLE_STRIP;
  • GL_TRIANGLE_FAN;
  • GL_TRIANGLES.

gl_blend_func() (analog of the glBlendFunc()) operations:
  • GL_ZERO;
  • GL_ONE;
  • GL_SRC_COLOR;
  • GL_ONE_MINUS_SRC_COLOR;
  • GL_DST_COLOR;
  • GL_ONE_MINUS_DST_COLOR;
  • GL_SRC_ALPHA;
  • GL_ONE_MINUS_SRC_ALPHA;
  • GL_DST_ALPHA;
  • GL_ONE_MINUS_DST_ALPHA;
  • GL_SRC_ALPHA_SATURATE.

State variables (for gl_get_int() and gl_get_float()):
  • GL_MAX_TEXTURE_SIZE;
  • GL_MAX_VERTEX_ATTRIBS;
  • GL_MAX_VERTEX_UNIFORM_VECTORS;
  • GL_MAX_VARYING_VECTORS;
  • GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS;
  • GL_MAX_TEXTURE_IMAGE_UNITS;
  • GL_MAX_FRAGMENT_UNIFORM_VECTORS.

Default shader names for the gl_new_prog():
  • GL_SHADER_SOLID - solid color;
  • GL_SHADER_GRAD - gradient color;
  • GL_SHADER_TEX_ALPHA_SOLID - solid color + one channel (opacity) texture;
  • GL_SHADER_TEX_ALPHA_GRAD - gradient color + one channel (opacity) texture;
  • GL_SHADER_TEX_RGB_SOLID - solid color + texture;
  • GL_SHADER_TEX_RGB_GRAD - gradient color + texture.

Global OpenGL containers:
  • GL_SCREEN; you can't read pixels from GL_SCREEN directly, but you can use copy( destination, GL_SCREEN ) for this;
  • GL_ZBUF.

Audio

Flags for set_audio_callback() function:

  • AUDIO_FLAG_INTERP2 - linear interpolation (2 points).

MIDI

Flags for midi_get_device(), midi_open_port() functions:

  • MIDI_PORT_READ;
  • MIDI_PORT_WRITE.

Events

  • EVT - ID of the container with event, which used by get_event() function.
EVT field numbers:
  • EVT_TYPE - event type;
  • EVT_FLAGS - event flags;
  • EVT_TIME - event time;
  • EVT_X (0 - center of the screen);
  • EVT_Y (0 - center of the screen);
  • EVT_KEY - ASCII code of pressed key, or one of the KEY_* constants;
  • EVT_SCANCODE - key scancode, or touch number for multitouch devices;
  • EVT_PRESSURE - touch pressure (normal - 1024).
Event types (for the EVT_TYPE field):
  • EVT_MOUSEBUTTONDOWN - first touch;
  • EVT_MOUSEBUTTONUP;
  • EVT_MOUSEMOVE;
  • EVT_TOUCHBEGIN - 2th, 3th etc. touch; only for multitouch devices;
  • EVT_TOUCHEND;
  • EVT_TOUCHMOVE;
  • EVT_BUTTONDOWN;
  • EVT_BUTTONUP;
  • EVT_SCREENRESIZE;
  • EVT_QUIT - Virtual Machine will be closed; if EVT[ EVT_SCANCODE ] = 0, this event can't be ignored, user code must be terminated as soon as possible; if EVT[ EVT_SCANCODE ] = 1, this event can be ignored by user.
Event flags (for the EVT_FLAGS field):
  • EVT_FLAG_SHIFT;
  • EVT_FLAG_CTRL;
  • EVT_FLAG_ALT;
  • EVT_FLAG_MODE;
  • EVT_FLAG_MODS (mask with all modifiers like Shift, Ctrl, etc.);
  • EVT_FLAG_DOUBLECLICK.
Event key codes (for the EVT_KEY field):
  • KEY_MOUSE_LEFT;
  • KEY_MOUSE_MIDDLE;
  • KEY_MOUSE_RIGHT;
  • KEY_MOUSE_SCROLLUP;
  • KEY_MOUSE_SCROLLDOWN;
  • KEY_BACKSPACE;
  • KEY_TAB;
  • KEY_ENTER;
  • KEY_ESCAPE;
  • KEY_SPACE;
  • KEY_F1;
  • KEY_F2;
  • KEY_F3;
  • KEY_F4;
  • KEY_F5;
  • KEY_F6;
  • KEY_F7;
  • KEY_F8;
  • KEY_F9;
  • KEY_F10;
  • KEY_F11;
  • KEY_F12;
  • KEY_UP;
  • KEY_DOWN;
  • KEY_LEFT;
  • KEY_RIGHT;
  • KEY_INSERT;
  • KEY_DELETE;
  • KEY_HOME;
  • KEY_END;
  • KEY_PAGEUP;
  • KEY_PAGEDOWN;
  • KEY_CAPS;
  • KEY_SHIFT;
  • KEY_CTRL;
  • KEY_ALT;
  • KEY_MENU;
  • KEY_UNKNOWN (system virtual key code = code - KEY_UNKNOWN).
Constants for the set_quit_action() function:
  • QA_NONE;
  • QA_CLOSE_VM.

Threads

Flags for thread_create():

  • THREAD_FLAG_AUTO_DESTROY - thread with this flag will be destroyed automatically.

Mathematical constants

  • M_E - e.
  • M_LOG2E - log2e.
  • M_LOG10E - log10e.
  • M_LN2 - loge2.
  • M_LN10 - loge10.
  • M_PI - PI.
  • M_2_SQRTPI - 2 / sqrt( PI ).
  • M_SQRT2 - sqrt( 2 ).
  • M_SQRT1_2 - 1 / sqrt( 2 ).

Data processing operations

For op_cn() function:

  • OP_MIN - op_cn() return value = min( C1[ i ], C1[ i + 1 ], ... );
  • OP_MAX - op_cn() return value = max( C1[ i ], C1[ i + 1 ], ... );
  • OP_MAXABS - op_cn() return value = max( | C1[ i ] + N |, | C1[ i + 1 ] + N |, ... );
  • OP_SUM - op_cn() return value = C1[ i ] + C1[ i + 1 ] + ... ;
  • OP_LIMIT_TOP - if C1[ i ] > N { C1[ i ] = N } ;
  • OP_LIMIT_BOTTOM - if C1[ i ] < N { C1[ i ] = N } ;
  • OP_ABS - absolute value;
  • OP_SUB2 - subtraction with reverse order of the operands (N - C1[ i ]);
  • OP_COLOR_SUB2 - color subtraction with reverse order of the operands (N - C1[ i ]);
  • OP_DIV2 - division with reverse order of the operands (N / C1[ i ]);
  • OP_H_INTEGRAL - running sum (horizontal);
  • OP_V_INTEGRAL - running sum (vertical);
  • OP_H_DERIVATIVE - first difference (horizontal);
  • OP_V_DERIVATIVE - first difference (vertical);
  • OP_H_FLIP;
  • OP_V_FLIP.

For op_cn(), op_cc() function:
  • OP_ADD - addition;
  • OP_SADD - addition with saturation;
  • OP_COLOR_ADD - color addition;
  • OP_SUB - subtraction;
  • OP_SSUB - subtraction with saturation;
  • OP_COLOR_SUB - color subtraction;
  • OP_MUL - multiplication;
  • OP_SMUL - multiplication with saturation;
  • OP_MUL_RSHIFT15 - ( C1[ i ] * N ) >> 15;
  • OP_COLOR_MUL - color multiplication;
  • OP_DIV - division;
  • OP_COLOR_DIV - color division;
  • OP_AND - bitwise AND;
  • OP_OR - bitwise OR;
  • OP_XOR - bitwise XOR;
  • OP_LSHIFT - bitwise left shift;
  • OP_RSHIFT - bitwise right shift;
  • OP_EQUAL;
  • OP_LESS;
  • OP_GREATER;
  • OP_COPY - copy;
  • OP_COPY_LESS - copy only if C1[ i ] < C2[ i ];
  • OP_COPY_GREATER - copy only if C1[ i ] > C2[ i ].

For op_cc() function:
  • OP_BMUL - if C2[ i ] == 0 { C1[ i ] = 0 };
  • OP_EXCHANGE;
  • OP_COMPARE - comparison; return value: 0 indicates that the contents are equal; 1 indicates that the first element that does not match in both containers has a greater value in C1 than in C2; -1 indicates the opposite.

For op_ccn() function:
  • OP_MUL_DIV - C1[ i ] * C2[ i ] / N;
  • OP_MUL_RSHIFT - ( C1[ i ] * C2[ i ] ) >> N (multiplication with bitwise right shift).

For generator() function:
  • OP_SIN - sine;
  • OP_SIN8 - fast, but rough sine (8bit table);
  • OP_RAND - pseudo random (from -amp to +amp).

Sampler

  • SMP_INFO_SIZE - size of the container with sample info.

Sample info field numbers:
  • SMP_DEST - destination container;
  • SMP_DEST_OFF - destination offset;
  • SMP_DEST_LEN - destination length;
  • SMP_SRC - container with sample;
  • SMP_SRC_OFF_H - sample offset (left part of fixed point value);
  • SMP_SRC_OFF_L - sample offset (right part of fixed point value from 0 to 65535);
  • SMP_SRC_SIZE - sample size (or 0 for whole sample);
  • SMP_LOOP - loop start;
  • SMP_LOOP_LEN - loop length (or 0, if no loop);
  • SMP_VOL1 - start volume (32768 = 1.0);
  • SMP_VOL2 - end volume (32768 = 1.0);
  • SMP_DELTA - delta (playing speed); fixed point (real_value * 65536);
  • SMP_FLAGS - flags.

Sample info flags:
  • SMP_FLAG_INTERP2 - linear interpolation (2 points);
  • SMP_FLAG_INTERP4 - cubic spline interpolation (4 points);
  • SMP_FLAG_PINGPONG - ping-pong loop;
  • SMP_FLAG_REVERSE - reverse direction.

Convolution filter flags

  • CONV_FILTER_COLOR;
  • CONV_FILTER_BORDER_EXTEND;
  • CONV_FILTER_BORDER_SKIP;
  • CONV_FILTER_UNSIGNED.

File dialog options

  • FDIALOG_FLAG_LOAD.

Native code

  • CCONV_DEFAULT;
  • CCONV_CDECL;
  • CCONV_STDCALL;
  • CCONV_UNIX_AMD64;
  • CCONV_WIN64.

POSIX

  • FOPEN_MAX;
  • SEEK_CUR;
  • SEEK_END;
  • SEEK_SET;
  • EOF;
  • STDIN;
  • STDOUT;
  • STDERR.

Pixilang info flags

  • PIXINFO_MULTITOUCH;
  • PIXINFO_TOUCHCONTROL;
  • PIXINFO_NOWINDOW;
  • PIXINFO_MIDIIN;
  • PIXINFO_MIDIOUT.

Misc

  • PIXILANG_VERSION - Pixilang version ((major<<24) + (minor<<16) + (minor2<<16) + minor3);
    example: PIXILANG_VERSION = 0x03040700 for v3.4.7;
  • OS_NAME - container with system name;
    examples: "ios", "win32", "linux";
  • ARCH_NAME - container with architecture name;
    examples: "x86", "x86_64", "arm", "mips";
  • LANG_NAME - container with the name of current system language (in POSIX format [language][_TERRITORY][.CODESET][@modifier]);
    examples: "en_US", "ru_RU.utf8";
  • CURRENT_PATH;
  • USER_PATH;
  • TEMP_PATH;
  • OPENGL - 1 if OpenGL available; 0 - otherwise;
  • INT_SIZE - max size (in bytes) of the signed integer;
  • FLOAT_SIZE - max size (in bytes) of the floating point number;
  • INT_MAX - max positive integer;
  • COLORBITS - number of bits per pixel.

Built-in global variables

  • WINDOW_XSIZE - user's window width (in pixels);
  • WINDOW_YSIZE - user's window height (in pixels);
  • WINDOW_SAFE_AREA_X;
  • WINDOW_SAFE_AREA_Y;
  • WINDOW_SAFE_AREA_W;
  • WINDOW_SAFE_AREA_H;
  • FPS - frames per second;
  • PPI - pixels per inch;
  • UI_SCALE - UI scale (defined by user in the global preferences); use it to scale your UI elements; for example: button_size = PPI * UI_SCALE * 0.5;
  • UI_FONT_SCALE - similar to UI_SCALE, but only for the text size;
  • PIXILANG_INFO - information (set of flags PIXINFO_*) about the current Pixilang runtime environment.

Reserved container properties

These properties can be used during playback, saving and loading of the containers:

  • file_format;
  • sample_rate;
  • channels;
  • loop_start - starting point (frame number) of the sample loop;
  • loop_len - sample loop length (number of frames);
  • loop_type - sample loop type: 0-none; 1-normal; 2-bidirectional;
  • frames - number of frames;
  • frame - current frame number;
  • fps - frames per second;
  • play - auto-play status (0/1);
  • repeat - repeat count (-1 - infinitely);
  • start_time - start time (in system ticks); automatically set by play();
  • start_frame - start frame; automatically set by play().

Built-in functions

Containers (memory management)

new()

Create a new data container.

Note: immediately after its creation, the container may contain some random values. You should clean it up or fill it with useful data.

Parameters ( xsize, ysize, type )

  • xsize - width.
  • ysize - height.
  • type - type of the atomic element of the container. Valid values:
    • INT - signed integer (size depends on the version of Pixilang);
    • INT8 - signed integer (8 bit);
    • INT16 - signed integer (16 bit);
    • INT32 - signed integer (32 bit);
    • INT64 - signed integer (64 bit);
    • FLOAT - floating point (size depends on the version of Pixilang);
    • FLOAT32 - floating point (32 bit);
    • FLOAT64 - floating point (64 bit);
    • PIXEL - pixel; will be converted to type INTx, where x - number of bits per pixel;

Return value: ID of the container, or -1 (error).

Examplesp = new() //Create 1x1 container. Element type = pixel. p = new( 4 ) //Create 4x1 container. Element type = pixel. p = new( 4, 4 ) //Create 4x4 container. Element type = pixel. p = new( 4, 4, INT32 ) //Create 4x4 container. Element type = INT32.

remove()

Remove a container.

Parameters ( pixi )

  • pixi - container ID.

Examplesp = new() //Create new container remove( p ) //Remove it

remove_with_alpha()

Remove the container and its alpha channel (linked container).

Parameters ( pixi )

  • pixi - container ID.

resize()

Resize a container.

Parameters ( pixi, xsize, ysize, type, flags )

  • pixi - container ID;
  • xsize - new width (or -1 if width not changed);
  • ysize - height (or -1 if height not changed); optional;
  • type - type of the atomic element of the container (or -1 if type not changed); optional; valid values:
    • INT8 - signed integer (8 bit);
    • INT16 - signed integer (16 bit);
    • INT32 - signed integer (32 bit);
    • INT64 - signed integer (64 bit);
    • FLOAT32 - floating point (32 bit);
    • FLOAT64 - floating point (64 bit);
    • PIXEL - pixel; will be converted to type INTx, where x - number of bits per pixel;
  • flags - resizing flags (RESIZE_*); optional.

Return value: 0 - successful; 1 - error.

Examplesp = new( 4, 4 ) //Create new container resize( p, 32, 32 ) //Resize it from 4x4 to 32x1 resize( p, -1, 64 ) //Resize it from 32x32 to 32x64 remove( p ) //Remove

rotate()

Rotate the container by angle*90 degrees (clockwise).

Параметры ( pixi, angle )

convert_type()

Convert the type of a container.

Parameters ( pixi, new_type )

clean()

Clean a container (fill with zeroes or with selected values).

Parameters ( dest_cont, v, offset, count )

  • dest_cont - container ID;
  • v - value; optional; default - 0;
  • offset - offset in dest_cont; optional; default - 0;
  • count - number of elements to fill; optional; default - whole container.

Examplesp = new() //Create new container clean( p ) //Clean with zero clean( p, 3 ) clean( p, 3, 0, 24 ) //Fill 24 elements with value 3 remove( p ) //Remove

clone()

Make a duplicate of the container.

Parameters ( pixi )

  • pixi - container ID.

Return value: ID of the new container, or -1 (error).

copy()

Copy container elements from src to dest.

Parameters ( dest, src, dest_offset, src_offset, count, dest_step, src_step, flags )

  • dest - destination container;
  • src - source container;
  • dest_offset - offset in destination (first element to copy);
  • src_offset - offset in source (first element to copy);
  • count - number of elements to copy;
  • dest_step - destination writing step (default - 1);
  • src_step - source reading step (default - 1);
  • flags - COPY_* flags; optional.

Examples//Copy all elements from img1 to img2: copy( img2, img1 ) //Copy elements 8...200 from img1 to img2: copy( img2, img1, 8, 8, 200 ) //Copy elements 8...400 from img1 to img2 with step 2: copy( img2, img1, 8, 8, 200, 2, 2 )

Return value: number of copied elements.

get_size()

Get size of a container (number of elements).

Parameters ( pixi )

  • pixi - container ID.

Examplesp = new( 8, 8 ) //Create a new container 8x8 size = get_size( p ) //Save its size to the "size" variable remove( p )

get_xsize()

Get width of a container.

Parameters ( pixi )

  • pixi - container ID.

Examplesp = new( 8, 8 ) //Create a new container 8x8 xsize = get_xsize( p ) //Save its width to the "xsize" variable remove( p )

get_ysize()

Get height of a container.

Parameters ( pixi )

  • pixi - container ID.

Examplesp = new( 8, 8 ) //Create a new container 8x8 ysize = get_xsize( p ) //Save its height to the "ysize" variable remove( p )

get_esize()

Get the size of the element of a container (in bytes).

Parameters ( pixi )

  • pixi - container ID.

Examplesp = new( 8, 8, INT32 ) //Create a new container 8x8; element type = INT32 esize = get_esize( p ) //Save its element's size to the "esize" variable //Now esize = 4. remove( p )

get_type()

Get the type of the element of a container

Parameters ( pixi )

  • pixi - container ID.

Examplesp = new( 8, 8, FLOAT32 ) //Create a new container 8x8; element type = FLOAT32 type = get_type( p ) //Save its element's type to the "type" variable //Now type = FLOAT32. remove( p )

get_flags()

Get container flags.

Parameters ( pixi )

Return value: container flags.

set_flags()

Set container flags.

Parameters ( pixi, flags )

Examplesset_flags( img, GL_MIN_LINEAR | GL_MAG_LINEAR )

reset_flags()

Reset container flags.

Parameters ( pixi, flags )

get_prop()

Get property value of the container. Each container can have unlimited number of properties.

Another way to get a property - use a . (dot) operator. Example: value = image.fps

Parameters ( pixi, prop_name, def_value )

  • pixi - container ID;
  • prop_name - property name;
  • def_vaule - default value, if the property is not exists; optional.

Return value: value of selected property.

set_prop()

Set property value of the container.

Another way to set a property - use a . (dot) operator. Example: image.fps = 30

Parameters ( pixi, prop_name, value )

  • pixi - container ID;
  • prop_name - property name;
  • value.

Examplesp = new( 8, 8, INT32 ) //Create a new container set_prop( p, "speed", 777 ) //Add "speed" property to this container v = get_prop( p, "speed" ) //Read the value of "speed" property //Or more simple way: p.speed = 777 v = p.speed

remove_prop()

Remove the container property.

Parameters ( pixi, prop_name )

  • pixi - container ID;
  • prop_name - property name.

remove_props()

Remove all properties of the selected container.

Parameters ( pixi )

show_memory_debug_messages

Parameters ( enable )

zlib_pack()

Parameters ( source, level )

  • source - container that will be compressed;
  • level - Zlib compression level (Z_NO_COMPRESSION, Z_BEST_SPEED, Z_BEST_COMPRESSION, Z_DEFAULT_COMPRESSION); optional.

Return value: ID of the new compressed container (created from the source) or -1 in case of error.

zlib_unpack()

Parameters ( source )

  • source - container that will be decompressed.

Return value: ID of the new decompressed container (created from the source) or -1 in case of error.

Strings

num_to_str()

Aliases: num2str.

Convert number to string.

Parameters ( str, num, radix )

  • str - container for the string;
  • num - numeric value;
  • radix (supported values: 10 and 16); optional.

Examplesv = 45.64 s = "" num_to_str( s, v ) fputs( s ) fputs( "\n" )

str_to_num()

Aliases: str2num.

Convert string to number.

Parameters ( str )

  • str - container with the string.

Return value: numeric value.

Examplesa = str_to_num( "-55.44" ) b = a + 4

strcat()

Appends a copy of the source string to the destination string. Both strings can be with terminating null character or without it (if the size of the container = number of characters in the string). Size of the source string can be changed after this function executes.

Parameters ( destination, source )

Parameters ( dest, dest_offset, source, source_offset )

strcmp()

Compares the string str1 to the string str2. Both strings can be with terminating null character or without it (if the size of the container = number of characters in the string).

Parameters ( str1, str2 )

Parameters ( str1, str1_offset, str2, str2_offset )

Return value: a zero value indicates that both strings are equal; a value greater than zero indicates that the first character that does not match has a greater value in str1 than in str2; and a value less than zero indicates the opposite.

strlen()

Returns the length of string str. String can be with terminating null character or without it (if the size of the container = number of characters in the string).

Parameters ( str )

Parameters ( str, str_offset )

Return value: length of string str.

strstr()

Returns the offset of the first occurrence of str2 in str1, or a -1 if str2 is not part of str1.

Parameters ( str1, str2 )

Parameters ( str1, str1_offset, str2, str2_offset )

Return value: offset of the first occurrence of str2 in str1, or a -1 if str2 is not part of str1.

sprintf()

Writes into the container str a string consisting on a sequence of data formatted as the format argument specifies. Detailed format description can be found here: https://en.wikipedia.org/wiki/Printf_format_string

Parameters ( str, format, ... )

Return value: on success, the total number of characters written is returned; on failure, a negative number is returned.

Examplessprintf( str, "Some text\n" ) //Just write some text to the str sprintf( str, "Number: %d\n", 12 ) //Write signed decimal integer

printf()

Same as sprintf, but the destination is STDOUT.

Parameters ( format, ... )

fprintf()

Print formatted output to the stream (opened by fopen() or fopen_mem()).

Parameters ( stream, format, ... )

Log management

logf()

The same as printf, but the destination is the Pixilang log buffer.

Parameters ( format, ... )

get_log()

Get the Pixilang log buffer.

Return value: the new container with the log buffer; (container must be removed manually).

get_system_log()

Get the Pixilang system log buffer.

Return value: the new container with the system log buffer; (container must be removed manually).

Working with files

load()

Load container from the file.

Parameters ( filename, options )

Return value: the new loaded container, or -1 in case of error.

Examplesc = load( "smile.jpg" ) if c >= 0 { file_format = c.file_format //FORMAT_RAW / FORMAT_JPEG / ... if file_format == FORMAT_WAVE { printf( "This is audio file\n" ) } }

fload()

Load container from the stream (opened by fopen() or fopen_mem()).

Parameters ( stream, options )

Return value: the new loaded container, or -1 in case of error.

save()

Save container to the file.

Parameters ( pixi, filename, format, options )

  • pixi;
  • filename;
  • format (FORMAT_RAW, FORMAT_JPEG, FORMAT_PNG, FORMAT_GIF, FORMAT_WAVE, FORMAT_PIXICONTAINER);
  • options:
    • for JPEG: quality from 0 - worst to 100 - best;
    • for GIF: flags GIF_GRAYSCALE, GIF_DITHER.

Return value: 0 on success.

Examplesc = load( "smile.jpg" ) save( c, "smile.png", FORMAT_PNG ) save( c, "smile2.jpg", FORMAT_JPEG ) //Quality = 85 (default) save( c, "smile3.jpg", FORMAT_JPEG, 100 ) //Quality = 100

fsave()

Save container to the stream (opened by fopen() or fopen_mem()).

Parameters ( pixi, stream, format, options )

Return value: 0 on success.

get_real_path()

Convert Pixilang-style path (e.g. 1:/img.png) to the real filesystem path.

Parameters ( path )

Return value: the container with real filesystem path; (container must be removed manually).

Examplesfilename = "1:/some_file" realpath = get_real_path( filename ) printf( "File name: %s; Real path: %s\n", filename, realpath ) remove( realpath )

new_flist()
remove_flist()
get_flist_name()
get_flist_type()
flist_next()

Functions for getting a list of files.

Examplespath = CURRENT_PATH mask = -1 //Examples: "txt/doc", "avi"; or -1 for all files. fl = new_flist( path, mask ) if fl >= 0 { printf( "Some files found in %s\n", path ) while( 1 ) { file_name = get_flist_name( fl ) file_type = get_flist_type( fl ) //0 - file; 1 - directory; if file_type == 0 { printf( "FILE %s%s\n", path, file_name ) } else { printf( "DIR %s%s\n", path, file_name ) } if flist_next( fl ) == 0 //Go to the next file { //No more files break } } remove_flist( fl ) }

get_file_size()

Get the size of selected file.

Parameters ( filename )

get_file_format()

Get file (or stream, if filename == -1) format (one of the FORMAT_* constants).

Parameters ( filename, stream )

  • filename;
  • stream; optional.

Return value: file format (one of the FORMAT_* constants).

get_fformat_mime()

Get MIME type (string) for specified file format.

Parameters ( fileformat )

  • fileformat - one of the FORMAT_* constants.

Return value: MIME type (string container).

get_fformat_ext()

Get the extension (string) for specified file format.

Parameters ( fileformat )

  • fileformat - one of the FORMAT_* constants.

Return value: file extension (string container).

remove_file()

Parameters ( filename )

rename_file()

Parameters ( old_filename, new_filename )

copy_file()

Parameters ( source_filename, destination_filename )

create_directory()

Parameters ( directory_name, mode )

  • directory_name;
  • mode - system specific mode; optional.

set_disk0()

Use the _stream_ (opened by fopen() or fopen_mem()) as virtual disk 0:/ . _stream_ must point to the opened TAR archive.

Parameters ( stream )

  • stream - stream, or 0 if you want to disable disk 0:/

get_disk0()

fopen()

The fopen() function shall open the file whose pathname is the string pointed to by _filename_, and associates a stream with it.

Parameters ( filename, mode )

  • filename;
  • mode:
    • r or rb - open file for reading;
    • w or wb - truncate to zero length or create file for writing;
    • a or ab - append; open or create file for writing at end-of-file;
    • r+ or rb+ or r+b - open file for update (reading and writing);
    • w+ or wb+ or w+b - truncate to zero length or create file for update;
    • a+ or ab+ or a+b - append; open or create file for update, writing at end-of-file.

Return value: upon successful completion, fopen() shall return ID of the object controlling the stream; otherwise, 0 shall be returned.

Examplesf = fopen( "/tmp/data.txt", "rb" ) //Open file data.txt for reading fclose( f ) //...and close it.

fopen_mem()

Open the _data_ container as file.

Parameters ( data )

Return value: upon successful completion, fopen_mem() shall return ID of the object controlling the stream; otherwise, 0 shall be returned.

fclose()

The fclose() function shall cause the stream to be flushed and the associated file to be closed.

Parameters ( stream )

Return value: upon successful completion, fclose() shall return 0.

Examplesf = fopen( "/tmp/data.txt", "rb" ) //Open file data.txt for reading. c = fgetc( f ) //Get a byte from this file. fclose( f ) //Close the stream.

fputc()

Put a byte on a stream.

Parameters ( c, stream )

Examplesf = fopen( "/tmp/data.txt", "wb" ) //Open file data.txt for writing. fputc( 0x12, f ) //Put a byte 0x12 to this file. fclose( f ) //Close the stream.

fputs()

Put a string on a stream.

Parameters ( s, stream )

Examplesf = fopen( "/tmp/data.txt", "wb" ) //Open file data.txt for writing. str = "Hello!" fputc( str, f ) //Put a string "Hello!" to this file. fclose( f ) //Close the stream.

fwrite()

The fwrite() function shall write, from the container data, up to size bytes, to the stream pointed to by stream.

Parameters ( data, size, stream, data_offset_optional )

Return value: the number of bytes successfully written, which may be less than size if a write error is encountered.

Examplesf = fopen( "/tmp/data.txt", "wb" ) //Open file data.txt for writing. str = "Hello!" fwrite( str, 2, f ) //Put first two bytes from the string "Hello!" to this file. fclose( f ) //Close the stream.

fgetc()

Get a byte from a stream.

Parameters ( stream )

Return value: upon successful completion, fgetc() shall return the next byte from the input stream pointed to by stream.

fgets()

Get a string from a stream.

Parameters ( s, n, stream, offset )

Return value: length of the string.

Examplesstring = new( 256, 1, INT8 ) f = fopen( "/tmp/data.txt", "rb" ) //Open file data.txt for reading. fgets( string, 256, f ) //Get a string from this file. fclose( f ) //Close the stream.

fread()

The fread() function shall read into the container pointed to by data up to size bytes, from the stream pointed to by stream.

Parameters ( data, size, stream, data_offset_optional )

Return value: the number of bytes successfully read which is less than size only if a read error or end-of-file is encountered.

feof()

Test end-of-file indicator on a stream.

Parameters ( stream )

Return value: non-zero if the end-of-file indicator is set for stream.

fflush()

Flush a stream.

Parameters ( stream )

fseek()

Reposition a file-position indicator in a stream.

Parameters ( stream, offset, origin )

  • stream;
  • offset;
  • origin:
    • SEEK_SET - beginning of file;
    • SEEK_CUR - current position of the file pointer;
    • SEEK_END - end of file.

ftell()

Return a file offset in a stream.

Parameters ( stream )

Return value: the current value of the file-position indicator for the stream measured in bytes from the beginning of the file.

Examples//One of the ways to get the file size: f = fopen( "/tmp/data.txt", "rb" ) fseek( f, 0, SEEK_END ) size_of_file = ftell( f ) fclose( f )

setxattr()

Set an extended attribute value of the file.

Parameters ( path, attr_name, data, data_size_in_bytes, flags )

Return value: 0 on success, or -1 in case of error.

Graphics

frame()

Draw the current screen on the display and sleep for selected number of milliseconds.

Parameters ( delay, x, y, xsize, ysize )

  • delay - pause length in milliseconds;
  • x, y, xsize, ysize - region of the screen; optional parameters.

Return value:
  • 0 - successful;
  • -1 - no screen;
  • -2 - timeout (graphics engine is suspended?).

vsync()

Enable/disable vertical synchronization (when possible). vsync(1) - enable. vsync(0) - disable.

Parameters ( enable )

set_pixel_size()

Change the size of the screen pixels. Default size = 1.

Parameters ( size )

get_pixel_size()

Get the size of the screen pixel.

set_screen()

Set current screen - destination container (with image) for all graphic commands.ID of the default screen container is 0.

Parameters ( pixi )

  • pixi - ID of the container that will be used as the current screen.

get_screen()

Get current screen.

Return value: screen container ID.

set_zbuf()

Parameters ( zbuf_container )

Set container (INT32 elements) with Z-buffer.

get_zbuf()

clear_zbuf()

get_color()

Get color by r,g,b (red,green,blue).

Parameters ( red, green, blue )

  • red - red intensity (0..255);
  • green - green intensity (0..255);
  • blue - blue intensity (0..255).

Return value: color value.

get_red()

Get red component intensity in a selected color.

Parameters ( color )

Return value: red component intensity; from 0 to 255.

get_green()

Get green component intensity in a selected color.

Parameters ( color )

Return value: green component intensity; from 0 to 255.

get_blue()

Get blue component intensity in a selected color.

Parameters ( color )

Return value: blue component intensity; from 0 to 255.

get_blend()

Get an intermediate color value between two selected colors.

Parameters ( c1, c2, v )

  • c1 - first color;
  • с2 - second color;
  • v - position between c1 and c2:
    • 0 and lower - c1;
    • ...
    • 128 - (с1+с2)/2;
    • ...
    • 255 and higher - c2.

Return value: intermediate color value.

transp()

Set transparency.

Parameters ( t )

  • t - transparency from 0 to 255.

get_transp()

clear()

Clear current screen.

Parameters ( color )

dot()

Draw a dot.

Parameters ( x, y, color )

dot3d()

Draw a dot in 3D.

Parameters ( x, y, z, color )

get_dot()

Get a dot's color.

Parameters ( x, y )

Return value: color value.

get_dot3d()

Get a dot's color in 3D.

Parameters ( x, y, z )

Return value: color value.

line()

Draw a line.

Parameters ( x1, y1, x2, y2, color )

line3d()

Draw a line in 3D.

Parameters ( x1, y1, z1, x2, y2, z2, color )

box()

Draw a rectangle.

Parameters ( x, y, xsize, ysize, color )

fbox()

Draw a filled rectangle.

Parameters ( x, y, xsize, ysize, color )

pixi()

Display the container with image.

Parameters ( pixi_cont, x, y, color, xscale, yscale, src_x, src_y, src_xsize, src_ysize )

  • pixi_cont - container ID (source);
  • x;
  • y;
  • color - color of the filter; optional; default value is WHITE;
  • xscale - scaling factor (x axis); optional; default value is 1;
  • yscale - scaling factor (y axis); optional; default value is 1;
  • src_x - x offset in pixi_cont; default - 0;
  • src_y - y offset in pixi_cont; default - 0;
  • src_xsize - width of drawable pixi_cont region; default - width of pixi_cont;
  • src_ysize - height of drawable pixi_cont region; default - height of pixi_cont.

Examplespixi( image ) pixi( image, 10, 20 ) pixi( image, 30, 40, GREEN ) pixi( image, 90, 20, GREEN, 0.5, 0.5 )

triangles3d()

Draw array of triangles.

Parameters ( vertices, triangles, tnum )

  • vertices - container of vertices; width = 8; height = number of vertices; vertex data format: X, Y, Z, TextureX (0..Width), TextureY (0..Height), Unused, Unused, Unused;
  • triangles - container of triangles; width = 8; height = number of triangles; triangle data format: NumberOfVertex1, NumberOfVertex2, NumberOfVertex3, Color, Texture (or -1), Opacity (0..255), Unused, Order (triangles with lower Order value will be drawn first);
  • tnum - number of triangles; optional.

sort_triangles3d()

Sort triangles by Z value.

Parameters ( vertices, triangles, tnum )

  • vertices - container of vertices; format is the same as in triangles3d();
  • triangles - container of triangles; format is the same as in triangles3d();
  • tnum - number of triangles; optional.

set_key_color()

Set / reset the color of transparency in the container.

Parameters ( pixi, color )

  • pixi - container ID;
  • color - color to be transparent; ignore this parameter if you want to disable transparent color for this container.

get_key_color()

set_alpha()

Attach a container with alpha channel to another container. Alpha channel should be of type INT8.

Parameters ( pixi, alpha )

  • pixi - container ID;
  • alpha - container with alpha channel; ignore this parameter if you want to disable alpha-channel for the pixi container.

get_alpha()

Get linked container with the alpha channel.

Parameters ( cont )

Return value: container ID or -1 (if no alpha channel).

print()

Show text on the screen.

Parameters ( text, x, y, color, align, max_xsize, str_offset, str_size )

  • text - container with text;
  • x, y - point of the alignment;
  • color;
  • align - alignment; optional;
  • max_xsize; optional;
  • str_offset - offset (number of the first byte) inside container text; optional;
  • str_size - how many bytes to read from container text; optional.

Examplesprint( "Hello Pixi!", 0, 0 ) //color = WHITE; centered; print( "line1\nline2", 50, 50, RED ) //centered; print( "line1\nline2", -50, 50, RED, TOP | LEFT ) //alignment = top left;

get_text_xsize()
get_text_ysize()
get_text_xysize()

Parameters ( text, align, max_xsize, str_offset, str_size )

  • text;
  • align; optional;
  • max_xsize; optional;
  • str_offset - offset (number of the first byte) inside container text; optional;
  • str_size - how many bytes to read from container text; optional.

get_text_xsize() return value: text width in pixels.
get_text_ysize() return value: text height in pixels.
get_text_xysize() return value: text size in pixels; width = retval & 0xFFFF; height = ( retval >> 16 ) & 0xFFFF;

set_font()

Parameters ( first_char_utf32, font_image, xchars, ychars )

get_font()

Parameters ( char_utf32 )

Return value: the font container font for the specified character.

effector()

Apply an effect to selected screen area. Coordinates of this function can't be changed by t_* transformation functions.

Parameters ( type, power, color, x, y, xsize, ysize, x_step, y_step )

color_gradient()

Draw a color gradient.

Parameters ( color1, transp1, color2, transp2, color3, transp3, color4, transp4, x, y, xsize, ysize, x_step, y_step )

split_rgb()

Split a container (with pixels) by color channels (red, green, blue) and vice versa.

Parameters ( direction, image, red_channel, green_channel, blue_channel, image_offset, channel_offset, size )

  • direction: 0 - from image to RGB; 1 - from RGB to image;
  • image - source/destination container of type PIXEL;
  • red_channel - container with red components of the image; optional; can be -1;
  • green_channel - container with green components of the image; optional; can be -1;
  • blue_channel - container with blue components of the image; optional; can be -1;
  • image_offset - offset in the image container; optional;
  • channel_offset - offset in the channel containers; optional;
  • size - number of pixels to split; optional.

Examplesimg = load( "some_image.jpg" ) xsize = get_xsize( img ) ysize = get_ysize( img ) r = new( xsize, ysize, INT16 ) g = new( xsize, ysize, INT16 ) b = new( xsize, ysize, INT16 ) split_rgb( 0, img, r, g, b ) //Convert image to RGB //Get red value (from 0 to 255) of the first pixel: value = r[ 0 ]

split_ycbcr()

Same as split_rgb() but for YCbCr conversion.

OpenGL base

OpenGL-version of Pixilang is based on the OpenGL ES 2.0 with OpenGL ES Shading Language 1.0 (GLSL ES).
Here is very good OpenGL ES 2.0 Quick Reference Card.

set_gl_callback()

Set OpenGL frame drawing callback.

Parameters ( gl_callback, user_data )

  • gl_callback - callback function with parameters ($user_data); almost all graphics functions will be redirected to OpenGL within this callback;
  • user_data - some user-defined data that will be sent to gl_callback() during the frame redrawing.

Examplesfn gl_callback( $user_data ) { set_screen( GL_SCREEN ) //Enable OpenGL drawing mode clear( YELLOW ) set_screen( 0 ) //Back to the default screen } set_gl_callback( gl_callback, //OpenGL frame drawing function 0 ) //Some user-defined data while( 1 ) { while( get_event() ) { if EVT[ EVT_TYPE ] == EVT_QUIT { break2 } } frame() } set_gl_callback( -1 ) //Remove OpenGL callback

remove_gl_data()

Remove all GL-specific data from the container. This data will be created again inside the OpenGL drawing callback.

Parameters ( container )

update_gl_data()

Sends a request to update the OpenGL texture associated with container. Use this function if the contents (pixels) of the container have changed, but the size remains the same.

Parameters ( container )

gl_draw_arrays()

Hybrid of the OpenGL functions glColor4ub(), glBindTexture(), glVertexPointer(), glColorPointer(), glTexCoordPointer(), glDrawArrays().
Can only be used inside the OpenGL drawing callback.

Parameters ( mode, first, count, color_r, color_g, color_b, color_a, texture, vertex_array, color_array, texcoord_array )

  • mode - what kind of primitives to render:
    • GL_POINTS;
    • GL_LINE_STRIP;
    • GL_LINE_LOOP;
    • GL_LINES;
    • GL_TRIANGLE_STRIP;
    • GL_TRIANGLE_FAN;
    • GL_TRIANGLES;
  • first - starting index in the enabled arrays;
  • count - number of indices to be rendered;
  • color_r, color_g, color_b, color_a - RGBA color (only if color_array is not specified);
  • texture - container with texture, or -1;
  • vertex_array - INT8, INT16 or FLOAT32 container with vertices;
  • color_array - INT8 or FLOAT32 container with RGBA colors, or -1; optional;
  • texcoord_array - INT8, INT16 or FLOAT32 container with texture coordinates; optional.

gl_blend_func()

Full analog of the OpenGL function glBlendFunc() (specify pixel arithmetic) or glBlendFuncSeparate (if sfactor_alpha and dfactor_alpha are specified).
Can only be used inside the OpenGL drawing callback.

Call this function without parameters, if you want to reset pixel arithmetic to the default values.

Parameters ( sfactor, dfactor, sfactor_alpha, dfactor_alpha )

  • sfactor - specifies how the red, green, and blue blending factors are computed;
  • dfactor - specifies how the red, green, and blue destination blending factors are computed;
  • sfactor_alpha - specified how the alpha source blending factor is computed; optional;
  • dfactor_alpha - specified how the alpha destination blending factor is computed; optional.

gl_bind_framebuffer()

Convert specified pixel container (cnum) to the OpenGL framebuffer (with attached texture) and bind it.All rendering operations will be redirected to this framebuffer.To unbind - just call this function without parameters.Pixel size does not affect the bound framebuffer.
Can only be used inside the OpenGL drawing callback.

Parameters ( cnum )

gl_bind_texture()

Bind selected pixel container (cnum) to the specified texture image unit.
Can only be used inside the OpenGL drawing callback.

Parameters ( cnum, texture_unit )

  • cnum - pixel container;
  • texture_unit - texture image unit number: 1, 2, 3, ... ; 0 is the main texture unit used by pixi().

Examplefn gl_callback( $userdata ) { set_screen( GL_SCREEN ) gl_bind_texture( some_image2, 1 ) //bind some_image2 to texture unit 1 gl_bind_texture( some_image3, 2 ) //bind some_image3 to texture unit 2 gl_use_prog( gl_prog ) //Use user-defined GLSL program gl_uniform( gl_prog.g_texture2, 1 ) //set shader variable: g_texture2 = texture image unit 1 gl_uniform( gl_prog.g_texture3, 2 ) //set shader variable: g_texture3 = texture image unit 2 pixi( some_image ) gl_use_prog() //Back to default GLSL program set_screen( 0 ) //Back to the default screen } gl_vshader = GL_SHADER_TEX_RGB_SOLID //Vertex shader = default shader for solid primitives drawing gl_fshader = //Fragment shader "uniform sampler2D g_texture; //main texture image unit 0 (set by pixi()) uniform sampler2D g_texture2; //texture image unit 1 uniform sampler2D g_texture3; //texture image unit 2 uniform vec4 g_color; IN vec2 tex_coord_var; void main() { vec4 c1 = texture2D( g_texture, tex_coord_var ); vec4 c2 = texture2D( g_texture2, tex_coord_var ); vec4 c3 = texture2D( g_texture3, tex_coord_var ); gl_FragColor = ( c1 + c2 + c3 ) * g_color; } " gl_prog = gl_new_prog( gl_vshader, gl_fshader )

gl_get_int()

Get the value of the simple GL state variable. Full analog of the OpenGL function glGetIntegerv().
Can only be used inside the OpenGL drawing callback.

Parameters ( pname )

  • pname - symbolic constant indicating the state variable to be returned.

gl_get_float()

Get the value of the simple GL state variable. Full analog of the OpenGL function glGetFloatv().
Can only be used inside the OpenGL drawing callback.

Parameters ( pname )

  • pname - symbolic constant indicating the state variable to be returned.

OpenGL shaders

OpenGL-version of Pixilang uses OpenGL ES Shading Language 1.0 (GLSL ES) for the vertex and the fragment shaders.

Notes about the vertex shader syntax in Pixilang:

  • use IN instead of attribute and in qualifiers;
  • use OUT instead of varying and out qualifiers;
  • use LOWP, MEDIUMP and HIGHP instead of the lowp, mediump and highp qualifiers;
  • use PRECISION( P, T ) instead of precision P, T.

Notes about the fragment shader syntax in Pixilang:
  • use IN instead of varying and in qualifiers;
  • use LOWP, MEDIUMP and HIGHP instead of the lowp, mediump and highp qualifiers;
  • use PRECISION( P, T ) instead of precision P, T.

gl_new_prog()

Create a new GLSL program - container with a vertex shader and a fragment shader. You can use this function anywhere in your code. Shader code will be compiled, and the program will be linked later - during the gl_use_prog() function call.

Parameters ( vertex_shader, fragment_shader )

  • vertex_shader - container with the source code of the vertex shader, or one of the GL_SHADER_* constants (predefined shaders);
  • fragment_shader - container with the source code of the fragment shader, or one of the GL_SHADER_* constants (predefined shaders).

Return value: the new container with GLSL program, or negative value in case of some error; (container must be removed manually).

gl_use_prog()

Use the GLSL program previously created by the gl_new_prog() function.If you use this program first time - it will be compiled and linked.
Can only be used inside the OpenGL drawing callback.

Parameters ( prog )

gl_uniform()

Change the value of the uniform variable within the GLSL program.
Can only be used inside the OpenGL drawing callback.

gl_uniform() can also change the contents of arrays if you use this function as follows:gl_uniform( var_location, src_container, vector_size, first_vector, count ), where count is the number of vectors to write to the array.

Parameters ( var_location, v0, v1, v2, v3 )

  • var_location - location of the uniform variable to be modified; you can get it from the GLSL program container easily: PROGRAM.UNIFORM_NAME;
  • v0, v1, v2, v3 - new values to be used for the specified uniform variable; v1, v2 and v3 are optional; number of values depends the number of components in the data type of the specified uniform variable.

Examplesgl_use_prog( gl_prog ) //Use GLSL program gl_prog (vertex shader + fragment shader) gl_uniform( gl_prog.g_time, get_timer( 0 ) ) //Set value of uniform variable g_time

gl_uniform_matrix()

Change the value of the uniform matrix within the GLSL program.
Can only be used inside the OpenGL drawing callback.

Parameters ( size, matrix_location, transpose, matrix )

  • size - dimensionality of the matrix: 2 = 2x2 matrix; 3 = 3x3 matrix; 4 = 4x4 matrix;
  • var_location - location of the matrix to be modified; you can get it from the GLSL program container easily: PROGRAM.MATRIX_NAME;
  • transpose - transpose the matrix (0 - no; 1 - yes);
  • matrix - ID of the container with the matrix.

Examplesgl_use_prog( gl_prog ) //Use GLSL program gl_prog (vertex shader + fragment shader) gl_uniform( 4, gl_prog.g_mat, 0, source_matrix ) //Set value of uniform matrix g_mat

Animation

pack_frame()

Pack current frame (from container data to hidden storage with frames). Frame number must be stored in the "frame" container property.

Parameters ( pixi )

unpack_frame()

Unpack current frame (from hidden storage with frames to container data). Frame number must be stored in the "frame" container property.

Parameters ( pixi )

create_anim()

Create the hidden storage with frames (animation) in the selected container.

Parameters ( pixi )

remove_anim()

Remove the hidden storage with frames (animation) from the selected container.

Parameters ( pixi )

clone_frame()

Clone current frame. Frame number must be stored in the "frame" container property.

Parameters ( pixi )

remove_frame()

Remove current frame. Frame number must be stored in the "frame" container property.

Parameters ( pixi )

play()

Enable auto-play mode. Frame will be changed automatically during the pixi() function call.

Parameters ( pixi )

stop()

Disable auto-play mode.

Parameters ( pixi )

Transformation

Coordinate system transformation.

t_reset()

Reset transformation.

t_rotate()

Parameters ( angle, x, y, z )

  • angle - specifies the angle of rotation, in degrees;
  • x, y, z - specify the x, y, and z coordinates of a vector, respectively.

t_translate()

Parameters ( x, y, z )

t_scale()

Parameters ( x, y, z )

t_push_matrix()

Save current transformation matrix to the stack.

t_pop_matrix()

Restore previous saved transformation matrix from the stack.

t_get_matrix()

Get transformation matrix (4x4 FLOAT).

Parameters ( matrix_container )

t_set_matrix()

Set transformation matrix (4x4 FLOAT).

Parameters ( matrix_container )

t_mul_matrix()

Multiply transformation matrix (4x4 FLOAT). Current matrix = current matrix * matrix_container.

Parameters ( matrix_container )

t_point()

Transform point (container with 3 elements of type FLOAT).

Parameters ( point_coordinates )

Audio

set_audio_callback()

Parameters ( callback, userdata, sample_rate, format, channels, flags )

  • callback - audio callback (function address);
  • userdata - user-defined data for the callback;
  • sample_rate - sample rate; set it to 0, if you want to use the sample rate from the global Pixilang preferences;
  • format - sample format;
  • channels - number of channels;
  • flags - flags AUDIO_FLAG_*.

Examplesfn audio_callback( $stream, $userdata, $channels, $frames, $time ) { generator( OP_SIN, $channels[ 0 ], 0, 32767 / 2, 0.1, 0 ) //Left channel generator( OP_SIN, $channels[ 1 ], 0, 32767 / 2, 0.1, 0 ) //Right channel ret(1) //return values: // 0 - silence, output channels are not filled; // 1 - output channels are filled; // 2 - silence, output channels are filled with zeros (or values close to zero). } //Start audio: set_audio_callback( audio_callback, 0, 22050, INT16, 2, AUDIO_FLAG_INTERP2 )//Stop audio: set_audio_callback( -1 )

get_audio_sample_rate()

Parameters ( source )

  • source: 0 - local sample rate; 1 - global (from Preferences) sample rate.

Return value: sample rate in Hz.

enable_audio_input()

Parameters ( disable_enable )

get_note_freq()

Get the frequency of the specified note (using a fast, not very accurate algorithm).
Frequency of MIDI note = get_note_freq( midi_note, 0 ) / 64; (5 octaves lower)

Parameters ( note, finetune )

  • note - note number; 0 = C-0; 1 = C#0; 2 = D-0 ...
  • finetune - from -64 (previous note) to 64 (next note).

Return value: note frequency in Hz.

MIDI

midi_open_client()

Parameters ( client_name )

Return value: client ID or negative value in case of some error.

midi_close_client()

Parameters ( client_id )

midi_get_device()

Parameters ( client_id, device_num, flags )

Return value: selected device name, or -1 if not exists.

midi_open_port()

Parameters ( client_id, port_name, device_name, flags )

Return value: port ID or negative value in case of some error.

midi_reopen_port()

Parameters ( client_id, port_id )

midi_close_port()

Parameters ( client_id, port_id )

midi_get_event()

Parameters ( client_id, port_id, data_cont )

Return value: size of the current MIDI event (in bytes).

midi_get_event_time()

Parameters ( client_id, port_id )

Return value: time of the current event (in system ticks).

midi_next_event()

Go to the next event.

Parameters ( client_id, port_id )

midi_send_event()

Parameters ( client_id, port_id, data_cont, data_size, t )

SunVox

SunVox modular synth engine is now part of Pixilang since v3.8.
See the SunVox Library Documentation for a detailed description of all functions.

Time

start_timer()

Start selected timer.

Parameters ( timer_num )

get_timer()

Get value (in milliseconds) of selected timer.

Parameters ( timer_num )

Return value: 32bit value of selected timer (in milliseconds).

get_year()

get_month()

get_day()

get_hours()

get_minutes()

get_seconds()

get_ticks()

Get current system tick counter (32bit).

get_tps()

Get number of system ticks per second.

sleep()

Parameters ( delay )

  • delay - delay in milliseconds.

Events

get_event()

Get a new event from the system.

Return value: 0 - no events; 1 - event is received and placed into the container EVT.

set_quit_action()

Set the program's behavior when receiving event EVT_QUIT.

Parameters ( action )

  • action - action number.

Possible values for the action parameter:
  • QA_NONE - do nothing;
  • QA_CLOSE_VM (default) - close the current virtual machine, but don't quit from Pixilang.

Threads

thread_create()

Parameters ( thread_function, user_data, flags_optional )

Return value: thread ID or -1 if error occurred.

Examplesfn thread_body( $thread_id, $user_data ) { printf( "Thread code\n" ) } thread_id = thread_create( thread_body, 0 ) err = thread_destroy( thread_id, 1000 ) //Wait for the thread to terminate if err == 0 { printf( "Thread closed successful\n" ) } if err == 1 { printf( "Time-out. Thread is not closed\n" ) } if err == 2 { printf( "Some error occurred in thread_destroy() function\n" ) }

thread_destroy()

Parameters ( thread_id, timeout_ms )

  • thread_id;
  • timeout_ms - time-out in milliseconds; negative values - don't try to kill the thread after timeout; INT_MAX - infinite.

Return value:
  • 0 - thread closed successfully;
  • 1 - time-out;
  • 2 - some error.

mutex_create()

Examplesnew_mutex = mutex_create() mutex_lock( new_mutex ) mutex_unlock( new_mutex ) mutex_destroy( new_mutex )

mutex_destroy()

mutex_lock()

mutex_trylock()

mutex_unlock()

Mathematical

acos( x ); acosh( x ); asin( x ); asinh( x ); atan( x ); atanh( x ); ceil( x ); cos( x ); cosh( x ); exp( x ); exp2( x ); expm1( x ); abs( x ); floor( x ); mod( x, y ); log( x ); log2( x ); log10( x ); pow( base, exp ); sin( x ); sinh( x ); sqrt( x ); tan( x ); tanh( x );

rand() - get random number from 0 to 32767;
rand_seed( seed ) - set random seed.

Type punning

Read more about type punning

reinterpret_type()

Parameters ( value, mode, intermediate_value_bits )

  • value;
  • mode:
    • 0 - FLOAT -> X-bit FLOAT -> INT;
    • 1 - INT -> X-bit FLOAT -> FLOAT;
  • intermediate_value_bits - 32 or 64.

Return value: converted value (INT or FLOAT depending on mode).

Data processing

op_cn()

Execute data processing operation.Operands: - container C1 (destination); - numerical value N.

Operation expression: for each element of C1: C1[ i ] = C1[ i ] OP N, Where i - element number; OP - selected operation.

Parameters ( opcode, C1, N ) - for whole container C1

Parameters ( opcode, C1, N, x, xsize ) - for 1D region

Parameters ( opcode, C1, N, x, y, xsize, ysize ) - for 2D region

  • opcode - operation;
  • C1 - destination container;
  • N - numerical value;
  • x,y,xsize,ysize - region.

Examples//Add 32 to the whole container img: op_cn( OP_ADD, img, 32 ) //Add 32 to 128..256th elements of the container img: op_cn( OP_ADD, img, 32, 128, 128 ) //Add 32 to two-dimensional region (8,8,32,32) of elements: op_cn( OP_ADD, img, 32, 8, 8, 32, 32 )

op_cc()

Execute data processing operation.Operands: - container C1 (destination); - container C2 (source).

Operation expression: for each element of C1: C1[ i ] = C1[ i ] OP C2[ i ], Where i - element number; OP - selected operation.

Parameters ( opcode, C1, C2 ) - for whole container C1

Parameters ( opcode, C1, C2, dest_x, src_x, xsize ) - for 1D region

Parameters ( opcode, C1, C2, dest_x, dest_y, src_x, src_y, xsize, ysize ) - for 2D region

  • opcode - operation;
  • C1 - destination container;
  • C2 - source container;
  • x,y,xsize,ysize - region.

op_ccn()

Execute data processing operation.Operands: - container C1 (destination); - container C2 (source); - numerical value N.

Operation expression: for each element of C1: C1[ i ] = C1[ i ] OP C2[ i ] OP2 N, Where i - element number; OP - selected operation; OP2 - additional operation associated with OP.

Parameters ( opcode, C1, C2, N ) - for whole container C1

Parameters ( opcode, C1, C2, N, dest_x, src_x, xsize ) - for 1D region

Parameters ( opcode, C1, C2, N, dest_x, dest_y, src_x, src_y, xsize, ysize ) - for 2D region

  • opcode - operation;
  • C1 - destination container;
  • C2 - source container;
  • N - numerical value;
  • x,y,xsize,ysize - region.

generator()

Generate a signal.

Parameters ( opcode, pixi, phase, amplitude, delta_x, delta_y, x, y, xsize, ysize )

  • opcode - operation;
  • pixi - container;
  • phase;
  • amplitude;
  • delta_x;
  • delta_y;
  • x,y,xsize,ysize - region.

Examples//Generate a sine wave to the whole container img: generator( OP_SIN, img, 0, 1, 0.1, 0.1 ) //Generate a rough sine wave to the whole container img: generator( OP_SIN8, img, 0, 1, 0.1, 0.1 ) //Generate a sine wave to 8...128 elements of the container img: generator( OP_SIN, img, 0, 1, 0.1, 0.1, 8, 120 ) //Generate a sine wave to region (8,8,32,32) of the container img: generator( OP_SIN, img, 0, 1, 0.1, 0.1, 8, 8, 32, 32 )

wavetable_generator()

Very fast multichannel sampler, where the sample (table) is always looped and has a fixed size (32768).

Parameters ( dest, dest_offset, dest_length, table, amp, amp_delta, pos, pos_delta, gen_offset, gen_step, gen_count )

  • dest - audio destination (INT16 or FLOAT32 container);
  • dest_offset;
  • dest_length;
  • table - table with waveform (supported formats: 32768 x INT16, 32768 x FLOAT32);
  • amp - INT32 array of amplitudes (fixed point 16.16); after each sample, these values will increase by the values from amp_delta;
  • amp_delta - INT32 array of amplitude delta values (fixed point 16.16);
  • pos - INT32 array of wavetable positions (fixed point 16.16); after each sample, these values will increase by the values from pos_delta;
  • pos_delta - INT32 array of wavetable position delta values (fixed point 16.16);
  • gen_offset - number of the first generator;
  • gen_step - play every gen_step generator;
  • gen_count - total number of generators to play.

Return value: 0 if success.

sampler()

Parameters ( sample_info )

Examplessample_data = new( 256, 1, INT16 ) //16bit sample sample_info = new( SMP_INFO_SIZE, 1, INT32 ) clean( sample_info ) sample_info[ SMP_DEST ] = buffer //Destination container sample_info[ SMP_DEST_OFF ] = 0 //Destination offset sample_info[ SMP_DEST_LEN ] = 256 //Destination length sample_info[ SMP_SRC ] = sample_data sample_info[ SMP_SRC_OFF_H ] = 0 //Sample offset (left part of fixed point value) sample_info[ SMP_SRC_OFF_L ] = 0 //Sample offset (right part of fixed point value from 0 to 65535) sample_info[ SMP_SRC_SIZE ] = 0 //Sample size (0 - whole sample) sample_info[ SMP_LOOP ] = 0 //Loop start sample_info[ SMP_LOOP_LEN ] = 128 //Loop length (or 0, if no loop) sample_info[ SMP_VOL1 ] = 0 //Start volume sample_info[ SMP_VOL2 ] = 32768 //End volume (32768 = 1.0) sample_info[ SMP_DELTA ] = ( 1 << 16 ) //Delta; fixed point (real_value * 65536) sample_info[ SMP_FLAGS ] = SMP_FLAG_INTERP4 | SMP_FLAG_PINGPONG //Cubic spline interpolation and ping-pong loop sampler( sample_info ) //Go!

envelope2p()

Apply gain and DC-offset two-points envelope to selected container area. Without clipping.

Parameters ( data_cont, v1, v2, offset, size, dc_offset1, dc_offset2 )

  • data_cont - container with data (audio waveform, for example);
  • v1 - initial gain (0 - no signal; 32768 - original unchanged amplitude);
  • v2 - final gain (0 - no signal; 32768 - original unchanged amplitude);
  • offset - offset in the data_cont; optional; default - 0;
  • size - size of area for envelope; optional; default - whole container;
  • dc_offset1 - initial DC offset; optional; default - 0;
  • dc_offset1 - final DC offset; optional; default - 0.

gradient()

Parameters ( container, val1, val2, val3, val4, x, y, xsize, ysize, x_step, y_step )

fft()

Perform a fast fourier transform.

Parameters ( inverse, im, re, size )

new_filter()

Create a new filter with the following function:output[ n ] = ( a[ 0 ] * input[ n ] + a[ 1 ] * input[ n - 1 ] + ... + a[ a_count - 1 ] * input[ n - a_count - 1 ] + b[ 0 ] * output[ n - 1 ] + ... + b[ b_count - 1 ] * output[ n - b_count - 1 ] ) >> rshift;

Parameters ( flags_for_future_use )

Return value: ID of the new container with the filter.

remove_filter()

Parameters ( filter )

reset_filter()

Parameters ( filter )

init_filter()

Parameters ( filter, a, b, rshift, flags )

  • filter;
  • a - container with the feedforward filter coefficients;
  • b - container with the feedback filter coefficients; optional; can be -1 (for FIR filters);
  • rshift - bitwise right shift for fixed point computations; optional;
  • flags - for future use; optional.

Return value: 0 if success.

apply_filter()

Parameters ( filter, output, input, flags, offset, size )

  • filter;
  • output - output container;
  • input - input container;
  • flags - for future use; optional;
  • offset - output and input offset; optional;
  • size - size of the processed block; optional.

Return value: 0 if success.

replace_values()

For each element of dest container: dest[ i ] = values[ (unsigned)src[ i ] ].The dest container must have the same type as the values.

Parameters ( dest, src, values, dest_offset, src_offset, size )

  • dest - destination;
  • src - source;
  • values - substitution values;
  • dest_offset - offset in the destination container; optional;
  • src_offset - offset in the source container; optional;
  • size - number of elements to replace; optional.

Examples//Convert 8-bit image with palette to the screen pixel format: replace_values( scr, img8, palette )

copy_and_resize()

Parameters ( dest, src, flags, dest_x, dest_y, dest_rect_xsize, dest_rect_ysize, src_x, src_y, src_rect_xsize, src_rect_ysize )

  • dest - destination container;
  • src - source container;
  • flags - flags RESIZE_*; optional; default = RESIZE_INTERP1;
  • dest_x, dest_y, dest_rect_xsize, dest_rect_ysize, src_x, src_y, src_rect_xsize, src_rect_ysize - optional parameters.

conv_filter()

Apply the convolution filter (convolution matrix).

Parameters ( dest, src, kernel, div, offset, flags, kernel_xcenter, kernel_ycenter, dest_x, dest_y, src_x, src_y, xsize, ysize, xstep, ystep )

  • dest - destination container;
  • src - source container;
  • kernel - kernel container (convolution matrix);
  • div - division of the result value (default is 1); optional;
  • offset - offset of the result value (default is 0); optional;
  • flags - flags CONV_FILTER_*; optional;
  • kernel_xcenter - central element of the matrix horizontally (from 0; default is kernel width / 2); optional;
  • kernel_ycenter - central element of the matrix vertically (from 0; default is kernel height / 2); optional;
  • dest_x, dest_y, src_x, src_y, xsize, ysize, xstep, ystep - optional parameters.

Dialogs

file_dialog()

Open file dialog.

Parameters ( dialog_name, mask, id, default_name, flags )

  • dialog_name;
  • mask - file type mask (examples: "gif/jpg" for .gif and .jpg files; "" for all files);
  • id - name of the file for saving the current dialog state;
  • default_name - default file name; optional;
  • flags - flags FDIALOG_FLAG_*; optional.

Return value: string container with the name of the selected file; or -1 if file not selected; (container must be removed manually).

prefs_dialog()

Open window with global Pixilang preferences.

textinput_dialog()

Open SunDog-based text input dialog and return the entered string. Only Latin letters are supported now.

Parameters ( default_text, dialog_name )

  • default_text; optional;
  • dialog_name; optional.

Return value: string container with the entered text; or -1 in case of cancellation; (container must be removed manually).

Network

open_url()

Open web browser window with selected URL.

Parameters ( url_string )

Native code

dlopen()

Open dynamic library (for example - .DLL file in Windows, or .SO file in Linux).

Parameters ( lib_file_name )

Return value: library ID or -1 if error occured.

Examples//For example we have some C function int show_info( int x, int y, void* data ) //in mylib.dll library. //Let's call it from Pixilang: dl = dlopen( "mylib.dll" ) //Open the library if dl >= 0 { f = dlsym( dl, "show_info", "iip" ) //Get the function show_info() from dynamic library // "iip" - int int pointer if f >= 0 { retval = dlcall( dl, f, 1, 2, "blahblah" ) //Call the function show_info() with parameters 1, 2, "blahblah" } dlclose( dl ) //Close the library }

dlclose()

Close dynamic library.

Parameters ( lib_id )

dlsym()

Get symbol (function or variable) from dynamic library.

Parameters ( lib_id, symbol_name, format, calling_convention )

  • lib_id;
  • symbol_name - function/variable name;
  • format - function format; optional; text string with the following structure: "R(P)", where the R - return value type (one ascii character), P - parameter types (multiple ascii characters or empty); below is a list of characters that are used for the construction of this string:
    • v - void;
    • c - signed int8;
    • C - unsigned int8
    • s - signed int16;
    • S - unsigned int16;
    • i - signed int32;
    • I - unsigned int32;
    • l - signed int64;
    • L - unsigned int64;
    • f - float32;
    • d - double64;
    • p - pointer;
  • calling_convention - one of the CCONV_* constants; optional; default - CCONV_DEFAULT.

Return value: symbol ID or -1 if error occured.

dlcall()

Call the function from dynamic library.

Parameters ( lib_id, symbol_id, optional_function_parameters )

System functions

system()

Issue a OS command.

Parameters ( command )

Return value: termination status of the command.

Examples//Remove some file: system( "rm /tmp/data.txt" )

argc()

Returns the number of arguments.

argv()

Returns the container with selected argument.

Parameters ( n )

Examplesif argc() >= 4 { a = argv( 3 ) remove( a ) }

exit()

Quit from Pixilang.

Parameters ( exit_code )

Examplesexit( 4 ) //Exit with code 4