User Tools

Site Tools


pixilang:manual_en

Table of Contents

Русская версия

PDF version of this page

What is Pixilang

Pixilang — cross-platform programming language for graphics/sound applications and experiments. Originally created by Alexander Zolotov (NightRadio) and Mik Razuvaev (Goglus) for non-programmers, demosceners and designers.

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

Command line options

pixilang [options] [source_file_name]
[options]
  -c    generate bytecode; source_file_name.pixicode file will be produced.
        Note: *.pixicode files are architecture-dependent.

Basics

The basis of the Pixilang - are containers and variables.

Container is a two-dimensional array of elements. Each element is the number in a specific format. Each container has one format for all its elements. Each container has its own unique ID number.

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_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.

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.

Examples

x = new( 4 ) //Create a new container with 4 pixels. Store its ID into the variable x.
x[ 2 ] = WHITE //Assign the white color to a pixel with number 2.
remove( x ) //Remove this container
c = 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 container
str = "Hello" //"Hello" is the string container with five 8-bit characters (UTF-8 encoding).
//This container (with string) will be created only once, during the bytecode generation.
//You don't need to delete them manually.
str[ 0 ] = 'h' //Change first character from 'H' to 'h'.
a = 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 discardable cache files;
//  Android: internal files directory;
"2:/filename"

//File is in the temporary directory:
"3:/filename"

Built-in 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.

Priority Operator Description Result Example
0 % Modulo (remainder) Integer a = b % 4
0 / Division Floating point a = b / 4
0 div Integer division Integer a = b div 4
0 * Multiplication Depends on the operands a = b * 4
1 + Addition Depends on the operands a = b + 4
1 - Subtraction Depends on the operands a = b - 4
2 >> Bitwise right shift Integer a = b >> 4
2 << Bitwise left shift Integer a = b << 4
3 == Equal to Integer 1 or 0 if a == b {}
3 != Not equal to Integer 1 or 0 if a != b {}
3 < Less than Integer 1 or 0 if a < b {}
3 > Greater than Integer 1 or 0 if a > b {}
3 <= Less than or equal to Integer 1 or 0 if a <= b {}
3 >= Greater than or equal to Integer 1 or 0 if a >= b {}
4 | Bitwise OR Integer a = b | 4
4 ^ Bitwise XOR Integer a = b ^ 4
4 & Bitwise AND Integer a = b & 4
5 || Logical OR Integer 1 or 0 if a || b {}
5 && Logical AND Integer 1 or 0 if 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.

Sizes

  • 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.

ZLib

Compression levels:

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

File formats

  • FORMAT_RAW;
  • FORMAT_JPEG;
  • FORMAT_PNG;
  • FORMAT_GIF;
  • FORMAT_WAVE;
  • FORMAT_AIFF (load only);
  • FORMAT_PIXICONTAINER - entire Pixilang container with properties and animation.

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.

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_xxx constants;
  • EVT_SCANCODE - key scancode, or touch number for multitouch devices;
  • EVT_PRESSURE - touch pressure (normal - 1024);
  • EVT_UNICODE.

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.

Native code constants

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

Constants for POSIX compatibility

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

Various

  • 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.

Built-in global variables

  • WINDOW_XSIZE - user's window width (in pixels);
  • WINDOW_YSIZE - user's window height (in pixels);
  • 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.

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 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).

Examples

p = 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.

Examples

p = 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 width not changed); optional;
  • type - type of the atomic element of the container (or -1 if width 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_xxx); optional.

Return value: 0 - successful; 1 - error.

Examples

p = 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.

Examples

p = 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_xxx 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.

Examples

p = 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.

Examples

p = 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.

Examples

p = 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.

Examples

p = 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.

Examples

p = 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. List of supported flags is here.

Parameters ( pixi )

Return value: container flags.

set_flags

Set container flags. List of supported flags is here.

Parameters ( pixi, flags )

Examples

set_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.

Examples

p = 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_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 )

  • str - container for the string;
  • num - numeric value.

Examples

v = 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.

Examples

a = 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: http://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.

Examples

sprintf( 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 - STDOUT.

Parameters ( format, … )

fprintf

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

Parameters ( stream, format, … )

Log management

logf

Send formatted output to 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: ID of the new loaded container, or -1 in case of error.

Examples

c = 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: ID of 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.

Examples

c = 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: ID of the container with real filesystem path; (container must be removed manually).

Examples

filename = "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.

Examples

path = 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 )

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.

Examples

f = 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.

Examples

f = 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 )

Examples

f = 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 )

Examples

f = 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.

Examples

f = 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.

Examples

string = 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. ID of the default screen container is 0.

Parameters ( pixi )

  • pixi - ID of the container with image which will be used as the 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 - closer to c1; 255 - closer to 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.

Examples

pixi( 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), Transparency (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 )

  • text - container with text;
  • x, y - point of the alignment;
  • color;
  • align - alignment;
  • max_xsize; optional.

Examples

print( "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

Parameters ( text, align, max_xsize )

  • text;
  • align;
  • max_xsize; optional.

Return value: text width in pixels.

get_text_ysize

Parameters ( text, align, max_xsize )

  • text;
  • align;
  • max_xsize; optional.

Return value: text height in pixels.

set_font

Parameters ( first_char_utf32, font_image, xchars, ychars )

get_font

Parameters ( char_utf32 )

Return value: container ID with font for selected character.

effector

Apply an effect to selected screen area. Coordinates of this function can't be changed by t_xxx 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.

Examples

img = 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.

Examples

fn 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 )

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).
Can only be used inside the OpenGL drawing callback.

Parameters ( sfactor, dfactor )

gl_bind_framebuffer

Convert selected 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.
Can only be used inside the OpenGL drawing callback.

Parameters ( cnum )

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_xxx constants (predefined shaders);
  • fragment_shader - container with the source code of the fragment shader, or one of the GL_SHADER_xxx constants (predefined shaders).

Return value: ID of 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.

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.

Examples

gl_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 = 2×2 matrix; 3 = 3×3 matrix; 4 = 4×4 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.

Examples

gl_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 (4×4 FLOAT).

Parameters ( matrix_container )

t_set_matrix

Set transformation matrix (4×4 FLOAT).

Parameters ( matrix_container )

t_mul_matrix

Multiply transformation matrix (4×4 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, freq, format, channels, flags )

Examples

fn 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)
}
//Start audio:
set_audio_callback( audio_callback, 0, 22050, INT16, 2, AUDIO_FLAG_INTERP2 )
//Stop audio:
set_audio_callback( -1 )

enable_audio_input

Parameters ( disable_enable )

get_note_freq

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.

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.

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 )

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.

Examples

fn 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

Examples

new_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.

Data processing

op_cn

Execute data processing operation. Operands:

  1. container C1 (destination);
  2. 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:

  1. container C1 (destination);
  2. 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:

  1. container C1 (destination);
  2. container C2 (source);
  3. 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 is always looped and fixed-size (256 for 8bit data, or 32768 for 16bit data).

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);
  • amp_delta - INT32 array of amplitude delta values (fixed point 16.16);
  • pos - INT32 array of wavetable positions (fixed point 16.16);
  • 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 )

Examples

sample_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_xxx; 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.

Dialogs

file_dialog

Open file dialog.

Parameters ( dialog_name, mask, id, default_name )

  • 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.

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

prefs_dialog

Open window with global Pixilang preferences.

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_xxx 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 )

Examples

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

exit

Quit from Pixilang.

Parameters ( exit_code )

Examples

exit( 4 ) //Exit with code 4
pixilang/manual_en.txt · Last modified: 2016/11/28 13:27 by nightradio