gfxboot reference

Abstract

Creating bootloader graphics with gfxboot for syslinux/isolinux, lilo, and
grub.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents

Overview
Utilities
syslinux Submenus
Reference
    Initialisation
    Callbacks
    Primary words

Overview

To make a graphical boot screen you'll have to write a small script. Optionally
you might want font files, graphics files and sound files.

The script is written in a Postscript-like language. You must program
everything related to graphics output in it. That does include e.g. drawing the
background picture and in particular handling all kind of user input.

Font files have a special format. Create them using gfxboot-font. Maximum font
file size is 512kB.

If you have written a script, convert it into byte code using gfxboot-compile.

Debugging this script is rather tedious. For this, gfxboot-compile -l will give
you debug information that is useful together with the dtrace command.

Utilities

Tools needed to build a boot graphics file.

  • gfxboot-compile

    Compile source into byte code. The result (together with any other files
    you might need) has to be put into a cpio archive. If you are using 
    isolinux or syslinux, this is not required, as you can read files directly
    from the filesystem. The compiled byte code, however, always has to be put
    into the cpio archive.

    Example 1. 

      # compile 'foo.ps' to 'foo', writing log to foo.log
      # Note: '-O' turns on the optimizer. You'll always want to do this.
      gfxboot-compile -O -v -l foo.log -c foo.ps foo

      # put it into a cpio archive
      # we'll assume you need a picture 'foo.jpg' and are using font 'foo.fnt'
      echo -e "foo\nfoo.jpg\nfoo.fnt" | cpio -o >bootlogo

      # 'bootlogo' is ready to use, e.g.
      # as 'gfxboot bootlogo' in isolinux.cfg



  • gfxboot-font

    Build font file using the freetype rendering engine.

  • help2txt

    Convert html files into the internal online-help format.

syslinux Submenus

gfxboot allows you to have submenus with syslinux (without the menu module) by
extending the syslinux config file syntax a bit.

Submenu entries have a label stating with '->FOO ' (note the space) where FOO
is an arbitrary string identifying the submenu.

Menu (or submenu) entries that have an append entry '->BAR' link to submenu BAR
. The maximum submenu nesting depth is 16.

As there are spaces in labels required to make this work, use the menu label
statement in syslinux.

Note that this way you can still use the label statement to reach any menu item
(even if it's in a submenu) directly, which keeps the config file also usable
in text mode.

Example 2. 


  # normal entry
  label linux
    kernel linux
    append initrd=initrd

  # link to submenu
  label submenu
    menu label My Submenu
    append ->1

  # 1st submenu entry
  label item1
    menu label ->1 Submenu Item #1
    kernel linux
    append initrd=initrd sub=1

  # 2nd submenu entry
  label item2
    menu label ->1 Submenu Item #2
    kernel linux
    append initrd=initrd sub=2




Reference

Comments start with '%' and extend to the end of line.

To include some other source file, do:

%% include file

Numbers are always 32 bit signed integer. Numerical and string constants are
given in a C-like way (not as in Postscript).

Example 3. 

    123, -456
    0x4567
    "Hi there\n"
    '\033', '\x1b', '\u20ac'



But: chars have values in the range 0 .. 0x1fffff.

Strings are interpreted as utf8-sequences. Alternatively you can use '\uXXXX'
or '\UXXXXXXXX' to include Unicode characters.

Example 4. 

     "1 Euro = 1 €\n"
     "1 Euro = 1 \u20ac\n"
     "1 Euro = 1 \xe2\x82\xac\n"



Logical operations return values of type 'bool'. They are not identical with
integers. There are no pre-defined constants 'true' and 'false'. But you can
define them yourself if you need them, e.g.:

/true 0 0 eq def

Strings and arrays are effectively pointers. So duplicating them on the stack
does duplicate the pointer, not the object.

In addition, there is a unspecific pointer data type. You can use it to
construct arbitrary memory references.

Variable/constants/function names can consist of everything except whitespace.

Initialisation

During initialization the config file in run. It must leave either an empty
stack or a boolean 'true' value at the TOS (top of stack) to indicate the boot
loader that everything worked fine. Otherwise the boot loader will assume that
some error occured and not continue in graphics mode.

If you want to handle input (as you probably do) you must define at least the
callback function KeyEvent.

Callbacks

Communication with the boot loader is done via callback functions. You are
responsible to assign useful actions to them. See config file examples for more
documentation.

  • KeyEvent

    Called if a key is pressed.

  • MenuInit

    Should draw boot menu.

  • InfoBoxInit

    Show message box (e.g. error messages).

  • InfoBoxDone

    Hide message box.

  • ProgressInit

    Initialize kernel load progress bar (syslinux/isolinux only).

  • ProgressDone

    Hide progress bar.

  • ProgressUpdate

    Advance progress bar.

  • PasswordInit

    Show password dialog.

  • PasswordDone

    Hide password dialog.

  • Timeout

    Timeout counter; called every 18.3th second until timeout occurs.

  • Timer

    Called every 18.3th second regardless of timeout.

Primary words

  • { – start code definition

    ( — code1 )

    code1: code start marker

    After {, no code is executed until a matching } is found.

    See also: def, }

    Example 5. 

      /++ { 1 add } def       % define increment function '++'



  • } – complete code definition

    ( — )

    Note: { and } are taken care of already during conversion into bytecode.
    This means that redefining them does not work as you would expect.

    See also: def, {

    Example 6. 

      /dec { 1 sub } def      % define decrement function 'dec'



  • 64bit – test if we run on a 64-bit machine

    ( — int1 )

    int1 = 1: 64-bit architecture

    See also: _readsector, date, eject, getbyte, getdword, getkey, getword,
    idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • [ – start array

    ( — mark1 )

    mark1: array start marker

    See also: ]

    Example 7. 

      [ 1 2 3 ]       % array with 3 elements



  • ] – complete array definition

    ( mark1 obj1 ... objN — array1 )

    mark1: array start marker

    obj1 ... objN: some objects

    array1: N-dimensional array with obj1 ... objN

    Note: The array uses dynamically allocated memory which must be released
    using free

    See also: [, array, chdir, dumpmem, filesize, findfile, free, getcwd,
    length, malloc, memcpy, memsize, realloc, snprintf

    Example 8. 

      /foo [ "some" "text" ] def      % array with 2 elements
      foo free                        % free memory



  • _readsector – read sector

    ( int1 — ptr1 )

    int1: sector number

    ptr1: sector data

    Note: internal function. Returns pointer to static buffer. Does not return
    on error. Returns .undef if function is not implemented.

    See also: 64bit, date, eject, getbyte, getdword, getkey, getword, idle,
    inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte, putdword,
    putword, realpath, reboot, serial.init, serialsetconfig, sysconfig,
    systempath, test1, time, usleep

  • abs – absolute value

    ( int1 — int2 )

    int2: |int1|

    See also: add, and, div, max, min, mod, mul, neg, not, or, shl, shr, sub,
    xor

    Example 9. 

      -6 abs          % 6



  • add – addition

    ( int1 int2 — int3 )

    ( string1 int4 — string2 )

    ( ptr1 int5 — ptr2 )

    int3: int1 + int2

    string2: substring of string1 at offset int4

    Note: Strings are treated as byte sequences, not Unicode chars. Sizes of
    string1 and ptr1 are not checked.

    See also: abs, and, div, max, min, mod, mul, neg, not, or, shl, shr, sub,
    xor

    Example 10. 

      1 2 add         % 3

      "abc" 1 add     % "bc"



  • and – logical or arithmetical 'and'

    ( int1 int2 — int3 )

    ( bool1 bool2 — bool3 )

    int3: int1 & int2

    bool3: bool1 && bool2

    Note: Mixing boolean and integer argument types is possible, in this case
    integers are converted to boolean first.

    See also: abs, add, div, max, min, mod, mul, neg, not, or, shl, shr, sub,
    xor

    Example 11. 

      true false and          % false

      3 6 and                 % 2

      10 true and             % gives true, but please avoid this



  • array – create an empty array

    ( int1 — array1 )

    int1: array dimension

    array1: new array

    Note: Use free to free array1.

    See also: ], chdir, dumpmem, filesize, findfile, free, getcwd, length,
    malloc, memcpy, memsize, realloc, snprintf

    Example 12. 

      /foo 10 array def       % create array with 10 elements
      foo 4 123 put           % foo[4] = 123
      foo free                % free foo



  • blend – - blend image with alpha channel

    ( obj1 obj2 ptr3 — )

    obj1: pointer to source image or color value

    obj2: pointer to alpha channel or transparency value

    ptr3: destination

    An image section of obj1 is copied to ptr3 using obj2 as alpha channel.
    obj1 may be a color value or an unpacked image (unpackimage, savescreen).
    obj2 may be a transparency value (0..255) or an unpacked image used as
    alpha channel. The current cursor position is used as offset into obj1 and
    obj2 if they are images. If both obj1 and obj2 are images, they must have
    the same dimensions.

    Note: 16/32-bit modes only.

    See also: currentimage, image, image.colors, image.size, loadpalette,
    restorescreen, savescreen, setimage, settransparentcolor, unpackimage

  • chdir – set current working directory

    ( str1 — )

    str1: file name

    See also: ], array, dumpmem, filesize, findfile, free, getcwd, length,
    malloc, memcpy, memsize, realloc, snprintf

    Example 13. 

      "/foo/bar" chdir        % set working directory



  • colorbits – current pixel size

    ( — int1 )

    int1: pixel size in bits

    See also: currentmode, displaysizes, monitorsize, screen.size, setmode,
    sysinfo, videomodeinfo, videomodes, vscreen.size

  • currentcolor – current drawing color

    ( — int1 )

    int1: palette index (8-bit mode) or 24-bit RGB-value (16/32-bit modes).

    See also: currentpoint, currenttransparency, fillrect, getpalette, getpixel
    , lineto, moveto, putpixel, rmoveto, screen.framebuffer, setcolor,
    setpalette, settransparency, show

    Example 14. 

      currentcolor not setcolor       % inverse color



  • currenteotchar – current alternative end-of-text char

    ( — int1 )

    int1: eot char

    See also: currentlink, currentmaxrows, currenttextcolors, currenttextwrap,
    currenttitle, formattext, getlink, getlinks, gettextrows, serialgetbaud,
    serialputc, seteotchar, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • currentfont – get current font

    ( — ptr1 )

    ( — int1 )

    ptr1: current font

    int1: current font, in password mode

    See also: fontheight, lineheight, setfont

    Example 15. 

      currentfont                             % save font
      "16x16_bold.fnt" findfile setfont       % set bold font
      "bold text" show                        % write something in bold font
      setfont                                 % back to normal font



  • currentimage – currently used image

    ( — ptr1 )

    See also: blend, image, image.colors, image.size, loadpalette,
    restorescreen, savescreen, setimage, settransparentcolor, unpackimage

  • currentlink – currently selected link

    ( — int1 )

    int1: selected link

    See also: currenteotchar, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setmaxrows, setstartrow,
    settextcolors, settextwrap, show, strsize

  • currentmaxrows – - current maxium number of text rows to display

    ( — int1 )

    int1: maxium number of text rows to display in a single show command.

    See also: currenteotchar, currentlink, currenttextcolors, currenttextwrap,
    currenttitle, formattext, getlink, getlinks, gettextrows, serialgetbaud,
    serialputc, seteotchar, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • currentmode – current video mode

    ( — int1 )

    int1: current video mode number

    See also: colorbits, displaysizes, monitorsize, screen.size, setmode,
    sysinfo, videomodeinfo, videomodes, vscreen.size

  • currentpoint – current cursor position

    ( — int1 int2 )

    int1, int2: x, y (upper left: 0, 0)

    See also: currentcolor, currenttransparency, fillrect, getpalette, getpixel
    , lineto, moveto, putpixel, rmoveto, screen.framebuffer, setcolor,
    setpalette, settransparency, show

  • currenttextcolors – current text markup colors

    ( — int1 int2 int3 int4 )

    int1: normal color

    int2: highlight color

    int3: link color

    int4: selected link color

    See also: currenteotchar, currentlink, currentmaxrows, currenttextwrap,
    currenttitle, formattext, getlink, getlinks, gettextrows, serialgetbaud,
    serialputc, seteotchar, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • currenttextwrap – current text wrap column

    ( — int1 )

    int1: text wrap column

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttitle, formattext, getlink, getlinks, gettextrows, serialgetbaud,
    serialputc, seteotchar, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • currenttitle – current page title

    ( — str1 )

    str1: page title

    Note: available after running formattext

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, formattext, getlink, getlinks, gettextrows, serialgetbaud,
    serialputc, seteotchar, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • currenttransparency – current transparency

    ( — int1 )

    See also: currentcolor, currentpoint, fillrect, getpalette, getpixel,
    lineto, moveto, putpixel, rmoveto, screen.framebuffer, setcolor, setpalette
    , settransparency, show

  • date – get current date

    ( — int1 )

    int1: date (bit 0-7: day, bit 8-15: month, bit 16-31: year)

    See also: 64bit, _readsector, eject, getbyte, getdword, getkey, getword,
    idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • def – define new word

    ( dict1 obj1 — )

    dict1: is defined as obj1

    See also: {, }

    Example 16. 

      /x 100 def              % define constant x as 100

      /neg { -1 mul } def     % define 'neg' function



  • displaysizes – supported display sizes

    ( — int1 int2 )

    int1, int2: width and height

    See also: colorbits, currentmode, monitorsize, screen.size, setmode,
    sysinfo, videomodeinfo, videomodes, vscreen.size

  • div – division

    ( int1 int2 — int3 )

    int3: int1 / int2

    See also: abs, add, and, max, min, mod, mul, neg, not, or, shl, shr, sub,
    xor

    Example 17. 

      17 3 div        % 5



  • dtrace – single step with debug window

    ( — )

    Turn on trace mode and show debug info in upper left screen corner.

    See also: trace

  • dumpmem – dump memory usage to console

    ( — )

    Note: useful only for debugging.

    See also: ], array, chdir, filesize, findfile, free, getcwd, length, malloc
    , memcpy, memsize, realloc, snprintf

  • dup – duplicate TOS

    ( obj1 — obj1 obj1 )

    See also: exch, index, over, pop, roll, rot

    Example 18. 

      key                             % key: some input value
      dup 'a' eq { do_a } if          % if key = 'a'
      dup 'b' eq { do_b } if          % if key = 'b'
      dup 'c' eq { do_c } if          % if key = 'c'
      pop



  • edit.done – restore input field background

    ( array1 — )

    array1: see edit.init

    Note: does not free any data associated with array1.

    See also: edit.getleft, edit.hidecursor, edit.init, edit.input, edit.redraw
    , edit.showcursor

    Example 19. 

      ed edit.done    % delete input field



  • edit.getleft – get chat left from cursor

    ( array1 — int1 )

    array1: see edit.init

    int1: char (0 = start of line)

    See also: edit.done, edit.hidecursor, edit.init, edit.input, edit.redraw,
    edit.showcursor

  • edit.hidecursor – hide input field cursor

    ( array1 — )

    array1: see edit.init

    See also: edit.done, edit.getleft, edit.init, edit.input, edit.redraw,
    edit.showcursor

  • edit.init – - setup and show an editable input field

    ( array1 str1 — )

    str1: initial input string value

    array1: (at least) 6-dimensional array: [ x y bg buf buf_size .undef ]. x,
    y: input field position; bg: background pixmap (created with savescreen) -
    this determines the input field dimensions, too; buf: string buffer, large
    enough for a string of length buf_size. The last element is used
    internally.

    See also: edit.done, edit.getleft, edit.hidecursor, edit.input, edit.redraw
    , edit.showcursor

    Example 20. 

      50 100 moveto 200 20 savescreen /bg exch def
      /buf 100 string def
      /ed [ 50 100 bg buf 100 .undef ] def
      ed "foo" edit.init



  • edit.input – edit field input processing

    ( array1 int1 — )

    array1: see edit.init

    int1: key (bits 0-23 Unicode char, bits 24-31 scan code)

    See also: edit.done, edit.getleft, edit.hidecursor, edit.init, edit.redraw,
    edit.showcursor

    Example 21. 

      /keyLeft 0x4b000000 def         % move cursor left
      ed 'a' edit.input
      ed keyLeft edit.input



  • edit.redraw – redraw input field

    ( array1 — )

    array1: see edit.init

    See also: edit.done, edit.getleft, edit.hidecursor, edit.init, edit.input,
    edit.showcursor

    Example 22. 

      ed edit.redraw          % redraw input field



  • edit.showcursor – show input field cursor

    ( array1 — )

    array1: see edit.init

    See also: edit.done, edit.getleft, edit.hidecursor, edit.init, edit.input,
    edit.redraw

  • eject – eject CD-ROM

    ( int1 — int2 )

    int1: BIOS drive id

    int2: BIOS error code

    Note: does not work with all BIOSes. (With very few, actually.)

    See also: 64bit, _readsector, date, getbyte, getdword, getkey, getword,
    idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • eq – equal

    ( int1 int2 — bool1 )

    ( str1 str2 — bool2 )

    ( obj1 obj2 — bool3 )

    bool1: true if int1 == int2

    bool2: true if str1 == str2

    bool3: true if obj1 and obj2 are identical

    See also: ge, gt, le, lt, ne

    Example 23. 

      1 3 eq                  % false
      "abc" "abc" eq          % true
      /a [ 1 2 ] def
      /b a def
      a [ 1 2 ] eq            % false (not the same array)
      a b eq                  % true



  • exch – exchange TOS with TOS-1

    ( obj1 obj2 — obj2 obj1 )

    See also: dup, index, over, pop, roll, rot

    Example 24. 

      8
      /a exch def     % a = 8



  • exec – evaluate object

    ( dict1 — )

    ( obj1 — obj1 )

    If obj1 is a dictionary entry, it is looked up and evaluated. If not, the
    stack is left unchanged.

    Note: Unlike Postscript, no cvx is necessary. And it works only with
    dictionary references.

    See also: exit, for, forall, if, ifelse, loop, repeat, return

    Example 25. 

      /foo [ /bar 100 "abc" ] def
      foo 0 get                       % /bar
      exec                            % run bar
      foo 2 get                       % "abc"
      exec                            % still "abc"



  • exit – leave loop/repeat/for/forall loop.

    ( — )

    See also: exec, for, forall, if, ifelse, loop, repeat, return

    Example 26. 

      0 1 100 { 56 eq { exit } if } for       % leave if counter == 56



  • filesize – get file size

    ( str1 — int1 )

    str1: file name

    int1: file length (or .undef if not found)

    Note: Unlike findfile, it doesn't load the file.

    See also: ], array, chdir, dumpmem, findfile, free, getcwd, length, malloc,
    memcpy, memsize, realloc, snprintf

    Example 27. 

      "xxx.jpg" filesize      % file size of "xxx.jpg"



  • fillrect – fill rectangular area

    ( int1 int2 — )

    int1, int2: width, height

    See also: currentcolor, currentpoint, currenttransparency, getpalette,
    getpixel, lineto, moveto, putpixel, rmoveto, screen.framebuffer, setcolor,
    setpalette, settransparency, show

    Example 28. 

      0 0 moveto
      blue setcolor
      300 200 fillrect        % 300x200 blue rectangle



  • findfile – load file

    ( str1 — ptr1 )

    str1: file name

    ptr1: buffer with file data

    Note: ptr1 may or may not have to be free'd using free, depending on
    whether it is actually loaded from file system or is part of the bootlogo
    archive. To be on the safe side, always free it.

    To get the file length, use length on ptr1.

    See also: ], array, chdir, dumpmem, filesize, free, getcwd, length, malloc,
    memcpy, memsize, realloc, snprintf

    Example 29. 

      "xxx.jpg" findfile length       % file size of "xxx.jpg"



  • fontheight – font height

    ( — int1 )

    int1: font height

    See also: currentfont, lineheight, setfont

    Example 30. 

      currentpoint
      "Hello" show                    % print "Hello"
      moveto 0 fontheight rmoveto
      "world!"                        % print "world!" below "Hello"



  • for – - typical 'for' loop

    ( int1 int2 int3 code1 — )

    int1: start value

    int2: step size

    int3: final value (inclusive)

    Run code1 and put the current counter value onto the stack for every
    iteration.

    See also: exec, exit, forall, if, ifelse, loop, repeat, return

    Example 31. 

      0 1 4 { } for           % leave 0 1 2 3 4 on the stack



  • forall – loop over all array elements

    ( array1 code 1 — )

    ( str1 code 1 — )

    ( ptr1 code 1 — )

    Run code1 for every element of array1, str1 or ptr1 putting each element on
    the stack in turn.

    Note: str1 is treated as a sequence of bytes, not utf8 chars.

    See also: exec, exit, for, if, ifelse, loop, repeat, return

    Example 32. 

      [ 1 2 3 ] { } forall    % leave 1 2 3 on the stack



  • formattext – - format text

    ( str1 — )

    str1: text

    Preprocess text to find (and remember) line breaks, links and stuff.

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setmaxrows, setstartrow,
    settextcolors, settextwrap, show, strsize

  • free – free memory

    ( obj1 — )

    obj1: object to free, either array, string or pointer

    Note: There is no garbage collector implemented. You have to keep track of
    memory usage yourself. If obj1 does not refer to some dynamically allocated
    object, free does nothing.

    See also: ], array, chdir, dumpmem, filesize, findfile, getcwd, length,
    malloc, memcpy, memsize, realloc, snprintf

    Example 33. 

      2 array                 % create array with 2 elements...
      free                    % and free it

      100 malloc              % allocate 100 bytes...
      free                    % and free it

      "Some Text" free        % free nothing



  • ge – greater or equal

    ( int1 int2 — bool1 )

    ( str1 str2 — bool2 )

    ( ptr1 ptr2 — bool3 )

    bool1: true if int1 >= int2

    bool2: true if str1 >= str2

    bool3: true if ptr1 >= ptr2

    See also: eq, gt, le, lt, ne

    Example 34. 

      7 4 ge                  % true
      "abc" "abc" ge          % true
      /a 10 malloc def
      /b a + 2 def
      b a ge                  % true



  • get – get array, string or memory element

    ( array1 int1 — obj1 )

    ( string1 int2 — int3 )

    ( ptr1 int4 — int5 )

    obj1: int1-th element of array1

    int3: int2-th byte of string1

    int5: int4-th byte of ptr1

    Note: Returns the n-th byte of string1, not the n-th utf8 char. Sizes of
    string1 or ptr1 are not checked.

    See also: put

    Example 35. 

      "abc" 1 get             % 'b'

      [ 10 20 30 ] 2 get      % 30



  • getbyte – get byte from memory

    ( ptr1 — int1 )

    int1: byte at ptr1

    See also: 64bit, _readsector, date, eject, getdword, getkey, getword, idle,
    inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte, putdword,
    putword, realpath, reboot, serial.init, serialsetconfig, sysconfig,
    systempath, test1, time, usleep

  • getcwd – get current working directory

    ( — str1 )

    str1: file name

    See also: ], array, chdir, dumpmem, filesize, findfile, free, length,
    malloc, memcpy, memsize, realloc, snprintf

    Example 36. 

      getcwd show     % print working directory



  • getdword – get dword from memory

    ( ptr1 — int1 )

    int1: dword at ptr1

    See also: 64bit, _readsector, date, eject, getbyte, getkey, getword, idle,
    inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte, putdword,
    putword, realpath, reboot, serial.init, serialsetconfig, sysconfig,
    systempath, test1, time, usleep

  • getkey – get keyboard input

    ( — int1 )

    int1: key (bit 0-7: ASCII, bit 8-15: scan code, bit 16-31: kbd status bits)

    Note: the function does not block. If there is no key pressed, bits 0-15
    will be 0.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getword, idle
    , inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte, putdword,
    putword, realpath, reboot, serial.init, serialsetconfig, sysconfig,
    systempath, test1, time, usleep

  • getlink – - get link information

    ( int1 — str1 str2 int2 int3 )

    int1: link number

    str1: link label

    str2: link text

    int1: link text x-offset

    int2: link text row

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setmaxrows, setstartrow,
    settextcolors, settextwrap, show, strsize

  • getlinks – - number of links in text

    ( — int1 )

    int1: number of links in text.

    Note: available after running formattext

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setmaxrows, setstartrow,
    settextcolors, settextwrap, show, strsize

  • getpalette – get palette entry

    ( int1 — int2 )

    int1: palette index

    int2: RGB value

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpixel, lineto, moveto, putpixel, rmoveto, screen.framebuffer, setcolor,
    setpalette, settransparency, show

    Example 37. 

      11 dup getpalette not setpalette        % invert color 11



  • getpixel – read pixel from graphics memory

    ( — int1 )

    int1: color; either 8-bit palette index or 24-bit RGB-value, depending on
    graphics mode.

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, lineto, moveto, putpixel, rmoveto, screen.framebuffer, setcolor
    , setpalette, settransparency, show

    Example 38. 

      getpixel not setcolor putpixel          % invert pixel color



  • gettextrows – number of text rows

    ( — int1 )

    int1: total number of text rows.

    Note: available after running formattext

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, serialgetbaud
    , serialputc, seteotchar, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • gettype – get object type

    ( obj1 — int1 )

    Returns the object type.

    See also: settype

    Example 39. 

      "abc" gettype           % 4 (= string)



  • getword – get word from memory

    ( ptr1 — int1 )

    int1: word at ptr1

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey, idle,
    inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte, putdword,
    putword, realpath, reboot, serial.init, serialsetconfig, sysconfig,
    systempath, test1, time, usleep

  • gt – greater than

    ( int1 int2 — bool1 )

    ( str1 str2 — bool2 )

    ( ptr1 ptr2 — bool3 )

    bool1: true if int1 > int2

    bool2: true if str1 > str2

    bool3: true if ptr1 > ptr2

    See also: eq, ge, le, lt, ne

    Example 40. 

      7 4 gt                  % true
      "abc" "abd" gt          % false
      /a 10 malloc def
      /b a + 2 def
      b a gt                  % true



  • idle – run stuff when idle

    ( ptr1 int1 — )

    ptr1: 'kroete' data

    int1: direction (0 or 1)

    Run 'kroete' animation while we're waiting for keyboard input.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, inbyte, keepmode, mount, notimeout, outbyte, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • if – typical 'if'

    ( bool1 code1 — )

    ( int1 code1 — )

    ( undef1 code1 — )

    ( obj1 code1 — )

    bool1: contition

    code1: code start marker (see {)

    int1: integer are automatically converted to boolean

    undef1: the undefined value is treated as 'false'

    obj1: strings, arrays, pointer are considered 'true'

    See also: exec, exit, for, forall, ifelse, loop, repeat, return

    Example 41. 

      10 4 gt { "10 > 4" show } if

      "" { "is always true" show } if         % strings are always 'true'



  • ifelse – typical 'if' / 'else'

    ( bool1 code1 code2 — )

    ( int1 code1 code2 — )

    ( undef1 code1 code2 — )

    ( obj1 code1 code2 — )

    bool1: contition

    code1: code start marker (see {) for 'true' branch

    code2: code start marker (see {) for 'false' branch

    int1: integer are automatically converted to boolean

    undef1: the undefined value is treated as 'false'

    obj1: strings, arrays, pointer are considered 'true'

    See also: exec, exit, for, forall, if, loop, repeat, return

    Example 42. 

      x1 x2 gt { "x1 > x2" } { "x1 <= x2" } ifelse show



  • image – show image region

    ( int1 int2 int3 int4 — )

    int1, int2: x, y position in image

    int3, int4: width, height of image region

    See also: blend, currentimage, image.colors, image.size, loadpalette,
    restorescreen, savescreen, setimage, settransparentcolor, unpackimage

    Example 43. 

      "xxx.jpg" findfile setimage     % load and activate "xxx.jpg"
      0 0 image.size image            % draw whole image



  • image.colors – image palette entries

    ( — int1 )

    int1: number of colors in 8-bit PCX image.

    8-bit modes use a color palette. An image uses the first image.colors
    entries. If you want to define your own colors, use image.colors to get the
    first free palette entry. For 16/32-bit modes, 0 is returned.

    See also: blend, currentimage, image, image.size, loadpalette,
    restorescreen, savescreen, setimage, settransparentcolor, unpackimage

  • image.size – graphics image size

    ( — int1 int2 )

    int1, int2: image width and height. The image is specified with setimage

    See also: blend, currentimage, image, image.colors, loadpalette,
    restorescreen, savescreen, setimage, settransparentcolor, unpackimage

    Example 44. 

      image.size screen.size
      exch 4 -1 roll sub 2 div 3 1 roll exch sub 2 div        % center image
      moveto 0 0 image.size image                             % draw it



  • inbyte – get byte from i/o port

    ( int1 — int2 )

    int2: byte from port int1

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, keepmode, mount, notimeout, outbyte, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • index – copy stack element

    ( objN ... obj1 int1 — objN ... obj1 objM )

    objM: M = int1 + 1

    See also: dup, exch, over, pop, roll, rot

    Example 45. 

      /dup { 0 index } def
      /over { 1 index } def



  • keepmode – keep video mode

    ( int1 — )

    int1 = 1: keep video mode when starting kernel.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, mount, notimeout, outbyte, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • le – less or equal

    ( int1 int2 — bool1 )

    ( str1 str2 — bool2 )

    ( ptr1 ptr2 — bool3 )

    bool1: true if int1 <= int2

    bool2: true if str1 <= str2

    bool3: true if ptr1 <= ptr2

    See also: eq, ge, gt, lt, ne

    Example 46. 

      7 7 le                  % true
      "abc" "abd" le          % true
      /a 10 malloc def
      /b a + 2 def
      b a le                  % false



  • length – array, string or memory size

    ( array1 — int1 )

    ( string1 — int1 )

    ( ptr1 — int1 )

    int1: size of array1 or string1 or ptr1

    Returns the length of string1 in bytes, not the number of Unicode chars. If
    ptr1 doesn't point at the start of a memory area, length returns the number
    of remaining bytes.

    See also: ], array, chdir, dumpmem, filesize, findfile, free, getcwd,
    malloc, memcpy, memsize, realloc, snprintf

    Example 47. 

      "abc" length            % 3

      [ 0 1 ] length          % 2

      /foo 10 malloc def
      foo length              % 10
      foo 3 add length        % 7



  • lineheight – current line height

    ( — int1 )

    int1: line height

    See also: currentfont, fontheight, setfont

  • lineto – draw line

    ( int1 int2 — )

    int1, int2: line end

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, getpixel, moveto, putpixel, rmoveto, screen.framebuffer,
    setcolor, setpalette, settransparency, show

    Example 48. 

      0 0 moveto screen.size lineto           % draw diagonal



  • loadpalette – load current palette

    ( — )

    Activates current palette in 8-bit modes.

    See also: blend, currentimage, image, image.colors, image.size,
    restorescreen, savescreen, setimage, settransparentcolor, unpackimage

  • loop – endless loop

    ( code1 — )

    See also: exec, exit, for, forall, if, ifelse, repeat, return

    Example 49. 

      /x 0 def { /x x 1 add def x 56 eq { exit } if } loop    % loop until x == 56



  • lt – less than

    ( int1 int2 — bool1 )

    ( str1 str2 — bool2 )

    ( ptr1 ptr2 — bool3 )

    bool1: true if int1 < int2

    bool2: true if str1 < str2

    bool3: true if ptr1 < ptr2

    See also: eq, ge, gt, le, ne

    Example 50. 

      7 4 lt                  % false
      "abc" "abd" lt          % true
      /a 10 malloc def
      /b a + 2 def
      b a lt                  % false



  • malloc – allocate memory

    ( int1 — ptr1 )

    int1: memory size

    ptr1: pointer to memory area

    Note: Use free to free ptr1.

    See also: ], array, chdir, dumpmem, filesize, findfile, free, getcwd,
    length, memcpy, memsize, realloc, snprintf

    Example 51. 

      /foo 256 malloc def     % allocate 256 bytes...
      foo free                % and free it



  • max – maximum

    ( int1 int2 — int3 )

    int3: max(int1, int2)

    See also: abs, add, and, div, min, mod, mul, neg, not, or, shl, shr, sub,
    xor

    Example 52. 

      4 11 max        % 11



  • memcpy – copy memory

    ( ptr1 ptr2 int1 — )

    ptr1: destination

    ptr2: source

    int1: size

    See also: ], array, chdir, dumpmem, filesize, findfile, free, getcwd,
    length, malloc, memsize, realloc, snprintf

    Example 53. 

      /a 10 malloc def
      /b 10 malloc def
      a 1 100 put             % a[1] = 100
      b a 10 memcpy           % copy a to b



  • memsize – report available memory size

    ( int1 — int2 int3 )

    int1: memory region (0 ... 3)

    int2: total free memory

    int3: size of largest free block

    Region 0 is memory in the low 640kB range. Region >= 1 are typically 1 MB
    extended memory per region.

    Note: available memory depends on the boot loader.

    See also: ], array, chdir, dumpmem, filesize, findfile, free, getcwd,
    length, malloc, memcpy, realloc, snprintf

    Example 54. 

      0 memsize pop 1024 lt { "less than 1kB left" show } if



  • min – minimum

    ( int1 int2 — int3 )

    int3: min(int1, int2)

    See also: abs, add, and, div, max, mod, mul, neg, not, or, shl, shr, sub,
    xor

    Example 55. 

      4 11 min        % 4



  • mod – remainder

    ( int1 int2 — int3 )

    int3: int1 % int2

    See also: abs, add, and, div, max, min, mul, neg, not, or, shl, shr, sub,
    xor

    Example 56. 

      17 3 mod        % 2



  • mod.load – assign mod file to player

    ( int1 ptr1 — )

    int1: player

    ptr1: mod file

    See also: mod.play, mod.playsample, sound.done, sound.getsamplerate,
    sound.getvolume, sound.play, sound.setsamplerate, sound.setvolume, wav.play
    , wav.playlater

  • mod.play – play mod file

    ( int1 int2 — )

    int1: player

    int2: song start

    Note: sounds are played using the PC speaker.

    See also: mod.load, mod.playsample, sound.done, sound.getsamplerate,
    sound.getvolume, sound.play, sound.setsamplerate, sound.setvolume, wav.play
    , wav.playlater

  • mod.playsample – play mod sample

    ( int1 int2 int3 int4 — )

    int1: player

    int2: channel

    int3: sample number

    int4: pitch

    See also: mod.load, mod.play, sound.done, sound.getsamplerate,
    sound.getvolume, sound.play, sound.setsamplerate, sound.setvolume, wav.play
    , wav.playlater

  • monitorsize – monitor size

    ( — int1 int2 )

    int1, int2: width and height

    See also: colorbits, currentmode, displaysizes, screen.size, setmode,
    sysinfo, videomodeinfo, videomodes, vscreen.size

  • mount – re-read filesystem meta data

    ( — int1 )

    int1: error

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, notimeout, outbyte, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

    Example 57. 

      mount pop       % re-read iso fs after cdrom change



  • moveto – set cursor position

    ( int1 int2 — )

    int1, int2: x, y (upper left: 0, 0).

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, getpixel, lineto, putpixel, rmoveto, screen.framebuffer,
    setcolor, setpalette, settransparency, show

    Example 58. 

      200 100 moveto "Hello" show     % print "Hello" at (200, 100)



  • mul – multiplication

    ( int1 int2 — int3 )

    int3: int1 * int2

    See also: abs, add, and, div, max, min, mod, neg, not, or, shl, shr, sub,
    xor

    Example 59. 

      2 3 mul         % 6



  • ne – not equal

    ( int1 int2 — bool1 )

    ( str1 str2 — bool2 )

    ( obj1 obj2 — bool3 )

    bool1: false if int1 == int2

    bool2: false if str1 == str2

    bool3: false if obj1 and obj2 are identical

    See also: eq, ge, gt, le, lt

    Example 60. 

      1 3 ne                  % true
      "abc" "abc" ne          % false
      /a [ 1 2 ] def
      /b a def
      a [ 1 2 ] ne            % true (not the same array)
      a b ne                  % false



  • neg – negation

    ( int1 — int2 )

    int2: -int1

    See also: abs, add, and, div, max, min, mod, mul, not, or, shl, shr, sub,
    xor

    Example 61. 

      5 neg           % -5



  • not – logical or arithmetical 'not'

    ( int1 — int2 )

    ( bool1 — bool2 )

    int2: -int1 - 1

    bool2: !bool1

    See also: abs, add, and, div, max, min, mod, mul, neg, or, shl, shr, sub,
    xor

    Example 62. 

      true not        % false

      0 not           % -1



  • notimeout – turn off initial boot loader timeout

    ( — )

    Turns off any automatic booting.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, outbyte, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • or – logical or arithmetical 'or'

    ( int1 int2 — int3 )

    ( bool1 bool2 — bool3 )

    int3: int1 | int2

    bool3: bool || bool2

    Note: Mixing boolean and integer argument types is possible, in this case
    integers are converted to boolean first.

    See also: abs, add, and, div, max, min, mod, mul, neg, not, shl, shr, sub,
    xor

    Example 63. 

      true false or           % true

      3 6 or                  % 7

      10 true or              % gives true, but please avoid this



  • outbyte – write byte to i/o port

    ( int1 int2 — )

    Write byte int2 to port int1.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, poweroff, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • over – copy TOS-1

    ( obj1 obj2 — obj1 obj2 obj1 )

    See also: dup, exch, index, pop, roll, rot

  • pop – remove TOS

    ( obj1 — )

    See also: dup, exch, index, over, roll, rot

    Example 64. 

                                      % status: true or false
      "bad" status { pop "ok" } if    % "bad" or "ok"



  • poweroff – switch computer off

    ( — )

    Note: uses APM, not ACPI.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, putbyte,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • put – set an array, string or memory element

    ( array1 int1 obj1 — )

    ( string1 int2 int3 — )

    ( ptr1 int4 int5 — )

    int1-th element of array1 = obj1

    int2-th byte of string1 = int3

    int4-th byte of ptr1 = int5

    Note: Sets the n-th byte of string1, not the n-th utf8 char. Sizes of
    string1 or ptr1 are not checked.

    See also: get

    Example 65. 

      /foo [ 10 20 30 ] def
      foo 2 77 put                    % foo = [ 10 20 77 ]

      /foo 10 string def
      foo 0 'a' put
      foo 1 'b' put                   % foo = "ab"

      But don't do this:
      "abc" 1 'X' put                 % modifies string constant "abc" to "aXc"!



  • putbyte – write byte to memory

    ( ptr1 int1 — )

    Write byte int1 at ptr1.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • putdword – write dword to memory

    ( ptr1 int1 — )

    Write dword int1 at ptr1.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putword, realpath, reboot, serial.init, serialsetconfig, sysconfig
    , systempath, test1, time, usleep

  • putpixel – draw single pixel

    ( — )

    Draw pixel in current color at current cursor position.

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, getpixel, lineto, moveto, rmoveto, screen.framebuffer, setcolor
    , setpalette, settransparency, show

    Example 66. 

      blue setcolor
      0 0 moveto putpixel     % blue dot at upper left corner



  • putword – write word to memory

    ( ptr1 int1 — )

    Write word int1 at ptr1.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • realloc – change allocated memory size

    ( obj1 int1 — )

    obj1: object to resize, either array, string or pointer

    int1: new size; memory is freed if zero

    Note: There is no garbage collector implemented. You have to keep track of
    memory usage yourself. If obj1 does not refer to some dynamically allocated
    object, realloc does nothing.

    See also: ], array, chdir, dumpmem, filesize, findfile, free, getcwd,
    length, malloc, memcpy, memsize, snprintf

    Example 67. 

      100 malloc      % allocate 100 bytes...
      10 realloc      % resize to 10 bytes



  • realpath – convert path to canonical absolute path

    ( str1 — str2 )

    str1: path

    str2: real path

    Note: str2 points to a static buffer.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, reboot, serial.init, serialsetconfig, sysconfig
    , systempath, test1, time, usleep

    Example 68. 

      "foo/bar" realpath



  • reboot – reboot computer

    ( — )

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, realpath, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time, usleep

  • repeat – repeat code

    ( int1 code1 — )

    Repeat code1 int1 times.

    See also: exec, exit, for, forall, if, ifelse, loop, return

    Example 69. 

      3 { "X" show } repeat           % print "XXX"



  • restorescreen – restore screen area

    ( ptr1 — )

    ptr1: buffer with image data; use free to free the buffer

    Note: width and height are taken from buffer. Does not actually free ptr1 -
    use free explicitly.

    See also: blend, currentimage, image, image.colors, image.size, loadpalette
    , savescreen, setimage, settransparentcolor, unpackimage

    Example 70. 

      0 0 moveto 100 100 savescreen           % save upper left 100x100 section...
      300 200 moveto dup restorescreen        % and copy it to 300x200
      free                                    % free memory



  • return – leave current function

    ( — )

    See also: exec, exit, for, forall, if, ifelse, loop, repeat

    Example 71. 

      /x {                                    % expects key on TOS
      dup 'a' eq { pop do_a return } if
      dup 'b' eq { pop do_b return } if
      dup 'c' eq { pop do_c return } if
      pop
      } def



  • rmoveto – set relative cursor position

    ( int1 int2 — )

    int1, int2: x-ofs, y-ofs.

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, getpixel, lineto, moveto, putpixel, screen.framebuffer,
    setcolor, setpalette, settransparency, show

    Example 72. 

      200 100 moveto
      "Hello" show
      30 0 rmoveto "world!"           % "Hello    world!" (approx.)



  • roll – rotate stack elements

    ( obj1 ... objN int1 int2 — objX ... objY )

    int1: number of elements to rotate

    int2: amount

    objX: X = (1 - int2) mod int1

    objY: Y = (N - int2) mod int1

    See also: dup, exch, index, over, pop, rot

    Example 73. 

      /rot { 3 -1 roll } def
      1 2 3 4 5 5 2 roll              % leaves: 4 5 1 2 3



  • rot – rotate TOS, TOS-1, TOS-2

    ( obj1 obj2 obj3 — obj2 obj3 obj1 )

    See also: dup, exch, index, over, pop, roll

    Example 74. 

      /a 4 array def
      8
      a 1 rot put             % a[1] = 8



  • savescreen – save screen area

    ( int1 int2 — ptr1 )

    int1, int2: width, height of screen area

    ptr1: buffer with image data; use free to free the buffer

    Note: width and height are stored in buffer.

    See also: blend, currentimage, image, image.colors, image.size, loadpalette
    , restorescreen, setimage, settransparentcolor, unpackimage

    Example 75. 

      0 0 moveto screen.size savescreen       % save entire screen



  • screen.framebuffer – ptr to framebuffer

    ( — ptr1 )

    ptr1: ptr to framebuffer or undef if no fb mode is active

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, getpixel, lineto, moveto, putpixel, rmoveto, setcolor,
    setpalette, settransparency, show

    Example 76. 

      screen.framebuffer



  • screen.size – screen size in pixel

    ( — int1 int2 )

    int1, int2: width, height

    See also: colorbits, currentmode, displaysizes, monitorsize, setmode,
    sysinfo, videomodeinfo, videomodes, vscreen.size

    Example 77. 

      blue setcolor
      0 0 moveto screen.size fillrect         % draw blue screen



  • serial.init – program serial lines

    ( — )

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, realpath, reboot, serialsetconfig, sysconfig,
    systempath, test1, time, usleep

  • serialgetbaud – get current baud rate

    ( int1 — int2 )

    int1: console

    int2: baud (0 = undefined)

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialputc, seteotchar, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • serialputc – write char to serial line

    ( int1 — )

    int1: char (bit 0-23: char, bit 24-31: console id)

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, seteotchar, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • serialsetconfig – set serial line config

    ( int1 int2 int3 — )

    int1: line number (0-4)

    int2: port

    int3: baud

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, realpath, reboot, serial.init, sysconfig,
    systempath, test1, time, usleep

  • setcolor – set active drawing color

    ( int1 — )

    int1: palette index (8-bit mode) or 24-bit RGB-value (16/32-bit modes).

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, getpixel, lineto, moveto, putpixel, rmoveto, screen.framebuffer
    , setpalette, settransparency, show

    Example 78. 

      0xff0000 setcolor       % continue in red...
      0xff00 setcolor         % or green...
      0xff setcolor           % or blue



  • seteotchar – set alternative end-of-text char

    ( int1 — )

    int1: eot char

    Normally strings are 0 terminated. seteotchar lets you define an additional
    char text functions recognize.

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, setlink, setmaxrows, setstartrow, settextcolors,
    settextwrap, show, strsize

  • setfont – set font

    ( ptr1 — )

    ( int1 — )

    ptr1: font data (e.g. font file).

    int1: same value as ptr1, but font is in password mode - it prints only
    '*'s.

    Note: password mode used to be passed as bit 31 in ptr1. gfxboot will try
    to guess if you are doing that, but please don't.

    See also: currentfont, fontheight, lineheight

    Example 79. 

      "16x16.fnt" findfile setfont    % set 16x16 font

      /pwmode { 1 settype } def
      currentfont pwmode setfont      % now in password mode
      "abc" show                      % print "***"



  • setimage – set active image

    ( ptr1 — )

    ptr1: image data. Either JPG or PCX file.

    Note: JPG is only supported in 16/32-bit modes.

    See also: blend, currentimage, image, image.colors, image.size, loadpalette
    , restorescreen, savescreen, settransparentcolor, unpackimage

    Example 80. 

      "foo.jpg" findfile setimage     % load and use "foo.jpg"



  • setlink – select link

    ( int1 — )

    int1: link number

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setmaxrows, setstartrow,
    settextcolors, settextwrap, show, strsize

  • setmaxrows – maximum number of text rows to display

    ( int1 — )

    int1: maximum number of text rows to display in a single show command.

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setstartrow, settextcolors,
    settextwrap, show, strsize

  • setmode – set video mode

    ( int1 — bool1 )

    int1: VESA or VGA mode number

    bool1: true = mode is set, false = failed

    Note: if video mode setting fails, the old mode is restored, but the screen
    contents is undefined.

    See also: colorbits, currentmode, displaysizes, monitorsize, screen.size,
    sysinfo, videomodeinfo, videomodes, vscreen.size

  • setpalette – set palette entry

    ( int1 int2 — )

    int1: palette index

    int2: RGB value

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, getpixel, lineto, moveto, putpixel, rmoveto, screen.framebuffer
    , setcolor, settransparency, show

    Example 81. 

      /red 11 0xff0000 def            % color 11 = red
      /yellow 12 0xffff00 def         % color 12 = yellow



  • setstartrow – set start row

    ( int1 — )

    int1: start row for next show command.

    Note: if a start row > 0 is set, the argument to show is irrelevant.
    Instead the internal data built during the last formattext is used.

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setmaxrows, settextcolors,
    settextwrap, show, strsize

  • settextcolors – - set text markup colors

    ( int1 int2 int3 int4 — )

    int1: normal color

    int2: highlight color

    int3: link color

    int4: selected link color

    Note: int1 can be changed using setcolor, too.

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setmaxrows, setstartrow,
    settextwrap, show, strsize

  • settextmodecolor – set color to be used in text mode

    ( int1 — )

    int1: text mode color

    Note: You only need this in case you're running in text mode (practically
    never).

  • settextwrap – set text wrap column

    ( int1 — )

    int1: text wrap column; set to 0 to turn text wrapping off.

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setmaxrows, setstartrow,
    settextcolors, show, strsize

  • settransparency – set transparency

    ( int1 — )

    int1: transparency for fillrect operations; valid values are 0 - 256.

    See also: currentcolor, currentpoint, currenttransparency, fillrect,
    getpalette, getpixel, lineto, moveto, putpixel, rmoveto, screen.framebuffer
    , setcolor, setpalette, show

  • settransparentcolor – set color used for transparency

    ( int1 — )

    When doing an image operation, pixels with this color are not copied.
    Something like an alpha channel, actually. Works only with PCX images. Not
    at all related to settransparency

    See also: blend, currentimage, image, image.colors, image.size, loadpalette
    , restorescreen, savescreen, setimage, unpackimage

  • settype – set object type

    ( obj1 int1 — obj2 )

    obj2: obj1 with type changed to int1.

    See also: gettype

    Example 82. 

                                                      % PS-like 'string' function
      /string { 1 add malloc 4 settype } def          % 4 = string type
      10 string                                       % new empty string of length 10



  • shl – shift left

    ( int1 int2 — int3 )

    int3: int1 << int2

    See also: abs, add, and, div, max, min, mod, mul, neg, not, or, shr, sub,
    xor

    Example 83. 

      5 2 shl         % 20



  • show – print text

    ( str1 — )

    Print str1 in current color using current font.

    See also: currentcolor, currenteotchar, currentlink, currentmaxrows,
    currentpoint, currenttextcolors, currenttextwrap, currenttitle,
    currenttransparency, fillrect, formattext, getlink, getlinks, getpalette,
    getpixel, gettextrows, lineto, moveto, putpixel, rmoveto,
    screen.framebuffer, serialgetbaud, serialputc, setcolor, seteotchar,
    setlink, setmaxrows, setpalette, setstartrow, settextcolors, settextwrap,
    settransparency, strsize

    Example 84. 

      "Hello world!" show     % print "Hello world!"



  • shr – shift right

    ( int1 int2 — int3 )

    int3: int1 >> int2

    See also: abs, add, and, div, max, min, mod, mul, neg, not, or, shl, sub,
    xor

    Example 85. 

      15 2 shr        % 3



  • snprintf – C-style snprintf

    ( obj1 ... objN str1 int1 ptr1 — )

    ptr1: buffer

    int1: buffer size

    str1: format string

    obj1 ... objN: printf arguments

    Note: reversed argument order!

    See also: ], array, chdir, dumpmem, filesize, findfile, free, getcwd,
    length, malloc, memcpy, memsize, realloc

    Example 86. 

      /sprintf {
      dup 12 settype length exch snprintf                     % 12 = pointer type
      } def

      /buf 100 string def
      "bar" "foo" 3 "%d %s %s" buf sprintf
      buf show                                                % print "3 foo bar"



  • sound.done – turn off sound subsystem

    ( — )

    See also: mod.load, mod.play, mod.playsample, sound.getsamplerate,
    sound.getvolume, sound.play, sound.setsamplerate, sound.setvolume, wav.play
    , wav.playlater

  • sound.getsamplerate – current sample rate

    ( — int1 )

    int1: sample rate

    See also: mod.load, mod.play, mod.playsample, sound.done, sound.getvolume,
    sound.play, sound.setsamplerate, sound.setvolume, wav.play, wav.playlater

  • sound.getvolume – current sound volume

    ( — int1 )

    int1: volume (0 .. 100)

    See also: mod.load, mod.play, mod.playsample, sound.done,
    sound.getsamplerate, sound.play, sound.setsamplerate, sound.setvolume,
    wav.play, wav.playlater

  • sound.play – play sound

    ( — )

    Note: obsolete. Sounds are played using the PC speaker.

    See also: mod.load, mod.play, mod.playsample, sound.done,
    sound.getsamplerate, sound.getvolume, sound.setsamplerate, sound.setvolume,
    wav.play, wav.playlater

  • sound.setsamplerate – set sample rate

    ( int1 — )

    int1: sample rate

    See also: mod.load, mod.play, mod.playsample, sound.done,
    sound.getsamplerate, sound.getvolume, sound.play, sound.setvolume, wav.play
    , wav.playlater

  • sound.setvolume – set sound volume

    ( int1 — )

    int1: volume (0 .. 100)

    See also: mod.load, mod.play, mod.playsample, sound.done,
    sound.getsamplerate, sound.getvolume, sound.play, sound.setsamplerate,
    wav.play, wav.playlater

  • strsize – text dimensions

    ( str1 — int1 int2 )

    int1, int2: width, height of str1.

    See also: currenteotchar, currentlink, currentmaxrows, currenttextcolors,
    currenttextwrap, currenttitle, formattext, getlink, getlinks, gettextrows,
    serialgetbaud, serialputc, seteotchar, setlink, setmaxrows, setstartrow,
    settextcolors, settextwrap, show

    Example 87. 

      "Hi there!"
      dup strsize pop neg 0 rmoveto show      % print "Hi there!" right aligned



  • strstr – find string in string

    ( str1 str2 — int1 )

    Search for str2 in str1.

    int1: offset of str2 in str1 + 1 if found; otherwise 0.

    Note: a bit strange, I know.

    Example 88. 

      "abcd" "c" strstr       % 3 (not 2)



  • sub – subtraction

    ( int1 int2 — int3 )

    ( string1 int4 — string2 )

    ( ptr1 int5 — ptr2 )

    ( string3 string4 — int6 )

    ( ptr2 ptr3 — int7 )

    int3: int1 - int2

    string2: substring of string1 at offset -int4

    int6: string3 - string4

    int7: ptr2 - ptr3

    Note: Strings are treated as byte sequences, not Unicode chars. Boundaries
    of string1 and ptr1 are not checked.

    See also: abs, add, and, div, max, min, mod, mul, neg, not, or, shl, shr,
    xor

    Example 89. 

      3 1 sub         % 2

      "abcd" 3 add    % "d"
      2 sub           % "bcd"



  • sysconfig – get pointer to boot loader config data

    ( — ptr1 )

    ptr1: boot loader config data (32 bytes)

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    systempath, test1, time, usleep

  • sysinfo – return system info

    ( int1 — obj1 )

    int1: info type

    obj1: info (or .undef)

    See also: colorbits, currentmode, displaysizes, monitorsize, screen.size,
    setmode, videomodeinfo, videomodes, vscreen.size

    Example 90. 

      0 sysinfo       % video mem size in kb
      1 sysinfo       % gfx card oem string
      2 sysinfo       % gfx card vendor string
      3 sysinfo       % gfx card product string
      4 sysinfo       % gfx card revision string



  • systempath – convert path to path relative to system working directory

    ( str1 — str2 )

    str1: path

    str2: system path

    Note: str2 points to a static buffer.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, test1, time, usleep

    Example 91. 

      "foo/bar" systempath



  • test1 – for internal testing

    ( ptr1 — )

    ptr1: some value with obscure meaning

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, time, usleep

    Example 92. 

      0x123 test1



  • time – get current time

    ( — int1 )

    int1: time in seconds since midnight.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, usleep

  • trace – single step

    ( — )

    Enter single step mode. Waits for a keypress after every instruction. Tab
    sets a temporary breakpoint after the current instruction and continues
    until it reaches it. Leave this mode by pressing Esc.

    See also: dtrace

  • unpackimage – unpack image region into buffer

    ( int1 int2 int3 int4 — ptr1 )

    int1, int2: x, y position in image

    int3, int4: width, height of image region

    ptr1: buffer with image data; use free to free the buffer

    See also: blend, currentimage, image, image.colors, image.size, loadpalette
    , restorescreen, savescreen, setimage, settransparentcolor

    Example 93. 

      "xxx.jpg" findfile setimage     % load and activate "xxx.jpg"
      0 0 10 10 unpackimage           % unpack upper left 10x10 region
      /img exch def                   % img = buffer

      0 10 100 {
      0 exch moveto
      img restorescreen
      } for                           % repeat image section horizontally 10 times

      img free                        % free it



  • usleep – sleep micro seconds

    ( int1 — )

    int1: micro seconds to sleep.

    Note: the actual granularity is 18Hz, so don't make up too sophisticated
    timings.

    See also: 64bit, _readsector, date, eject, getbyte, getdword, getkey,
    getword, idle, inbyte, keepmode, mount, notimeout, outbyte, poweroff,
    putbyte, putdword, putword, realpath, reboot, serial.init, serialsetconfig,
    sysconfig, systempath, test1, time

  • videomodeinfo – return video mode info

    ( int1 — int2 int3 int4 int5 )

    int1: mode index int2, int3: width, height

    int4: color bits

    int5: mode number (bit 14: framebuffer mode) or .undef

    See also: colorbits, currentmode, displaysizes, monitorsize, screen.size,
    setmode, sysinfo, videomodes, vscreen.size

    Example 94. 

      2 videomodeinfo



  • videomodes – video mode list length

    ( — int1 )

    int1: video mode list length (always >= 1)

    See also: colorbits, currentmode, displaysizes, monitorsize, screen.size,
    setmode, sysinfo, videomodeinfo, vscreen.size

  • vscreen.size – virtual screen size

    ( — int1 int2 )

    int1, int2: virtual width and height

    You normally can expect the virtual height to be larger than the visible
    height returned by screen.size That area is available e.g. for hidden
    drawing. Some kind of scrolling is not implemented, however.

    See also: colorbits, currentmode, displaysizes, monitorsize, screen.size,
    setmode, sysinfo, videomodeinfo, videomodes

  • wav.play – play wav file

    ( ptr1 — )

    ptr1: wav file

    See also: mod.load, mod.play, mod.playsample, sound.done,
    sound.getsamplerate, sound.getvolume, sound.play, sound.setsamplerate,
    sound.setvolume, wav.playlater

  • wav.playlater – play wav file after current one

    ( ptr1 — )

    ptr1: wav file

    See also: mod.load, mod.play, mod.playsample, sound.done,
    sound.getsamplerate, sound.getvolume, sound.play, sound.setsamplerate,
    sound.setvolume, wav.play

  • xor – logical or arithmetical exclusive 'or'

    ( int1 int2 — int3 )

    ( bool1 bool2 — bool3 )

    int3: int1 ^ int2

    bool3: bool ^^ bool2

    Note: Mixing boolean and integer argument types is possible, in this case
    integers are converted to boolean first.

    See also: abs, add, and, div, max, min, mod, mul, neg, not, or, shl, shr,
    sub

    Example 95. 

      true false xor          % true

      3 6 xor                 % 5

      10 true xor             % gives false, but please avoid this




