Biksel Programming Interface — Quick Reference

Program entry point

// Mode (io): Main
void Main(Channel io)
{
  // Your program here.
}

Basic data types

/* Primitive types:

Int32       (32-bit signed integer)
Int64       (64-bit signed integer)
Float64     (64-bit floating point number)

StaticText  (immutable text specified in double quotes)

*/

typedef Int32 Bool;
enum { False, True };

typedef Int32 MayTag;
enum { Nothing, Just };

typedef Int32 ListTag;
enum { Nil, Cons };

typedef struct {
  MayTag tag;
  Int32 value; // only valid if tag = Just
} MaybeInt32;

typedef struct {
  MayTag tag;
  Int64 value; // only valid if tag = Just
} MaybeInt64;

typedef struct {
  MayTag tag;
  Float64 value; // only valid if tag = Just
} MaybeFloat64;

Mathematical functions and constants

Float64 RoundHalfUp(Float64 x);
Float64 Floor(Float64 x);

Float64 Exp(Float64 x);
Float64 Log(Float64 x);

Float64 Pow(Float64 x, Float64 y);
Float64 Sqrt(Float64 x);

// Angles are in radians.

const Float64 Tau; // a full turn
const Float64 Pi;  // a half turn

// Components of a unit vector at an angle to the x-axis.
Float64 Cos(Float64 angle);
Float64 Sin(Float64 angle);

// Angle of a vector relative to the x-axis, between -Tau/2 and
// Tau/2.
Float64 Angle(Float64 x, Float64 y);

Keyboard keys

typedef Int32 Key;
enum {
  // CHARACTER KEYS

  // Letters
  KeyA, KeyB, KeyC, KeyD, KeyE, KeyF, KeyG, KeyH, KeyI, KeyJ,
  KeyK, KeyL, KeyM, KeyN, KeyO, KeyP, KeyQ, KeyR, KeyS, KeyT,
  KeyU, KeyV, KeyW, KeyX, KeyY, KeyZ,

  // Digits
  Key0, Key1, Key2, Key3, Key4,
  Key5, Key6, Key7, Key8, Key9,

  KeyBackquote,          KeyHyphen,              KeyEquals,
  KeyLeftSquareBracket,  KeyRightSquareBracket,  KeyBackslash,
  KeySemicolon,          KeySingleQuote,         KeyComma,
  KeyPeriod,             KeyForwardSlash,
  
  // British keyboard only
  KeyHash,

  // EDITING AND NAVIGATION KEYS

  KeyEscape,  KeyBackspace,  KeyTab,
  KeyReturn,  KeySpace,
  
  KeyInsert,  KeyDelete,  KeyHome,
  KeyEnd,     KeyPageUp,  KeyPageDown,
  
  // Arrow keys
  KeyLeft,  KeyRight,  KeyDown,  KeyUp,

  // NUMERIC KEYPAD
  
  // Digits.
  KeyNumpad0, KeyNumpad1, KeyNumpad2, KeyNumpad3, KeyNumpad4,
  KeyNumpad5, KeyNumpad6, KeyNumpad7, KeyNumpad8, KeyNumpad9,

  KeyNumpadDecimalPoint,
  
  KeyNumpadEnter,  KeyNumpadPlus,  KeyNumpadMinus,
  KeyNumpadTimes,  KeyNumpadDivide,

  // LOCK AND MODIFIER KEYS
  
  KeyCapsLock,  KeyNumLock,
  
  KeyLeftShift,  KeyRightShift,  KeyLeftCtrl,  KeyRightCtrl,
  KeyLeftAlt,
  
  // US keyboard only
  KeyRightAlt,
  
  // British keyboard only
  KeyAltGr,

  // FUNCTION KEYS

  KeyF1, KeyF2, KeyF3, KeyF4, KeyF5, KeyF6,
  KeyF7, KeyF8, KeyF9, KeyF10, KeyF11, KeyF12
};

Mouse buttons

typedef Int32 MouseButton;
enum {
  MouseLeft,
  MouseRight
};

Colours

const Color Transparent;

const Color Black;
const Color White;
const Color Red;
const Color Green;
const Color Blue;
const Color Cyan;
const Color Magenta;
const Color Yellow;

// 'red', 'green', 'blue', and 'level' must be in the range
// 0-255.
Color Rgb(Int32 red, Int32 green, Int32 blue);
Color Gray(Int32 level);

Sprites

// Mode (io): Main
// Returns a new channel in mode 'Sprite'.
Channel LoadNewSprite(StaticText name,
                      Channel io, StaticText path);

Fonts

// This channel is in mode 'Font'.
const Channel Mono11;

Text

// Mode (c): PutText
void PutText(Channel c, StaticText text);
void PutInt32AsText(Channel c, Int32 x);
void PutInt64AsText(Channel c, Int64 x);
void PutFloat64AsText(Channel c, Float64 x);

View transformations

const Trans FlipX;
const Trans FlipY;

Trans Scale(Int32 a);
Trans Rotate(Int32 quarterTurns);
Trans Translate(Int32 x, Int32 y);
Trans ClipToRect(Int32 x1, Int32 y1, Int32 x2, Int32 y2);

const Trans Identity;
Trans Compose(Trans b, Trans a);

Drawing graphics

// Mode (io): Main -> Draw >> EndDraw >> Main
void BeginDraw(Channel io);

// Mode (io): Draw >> EndDraw -> ()
void EndDraw(Channel io);

// Mode (io): Draw
void FillFrame(Channel io, Color col);
void FillTriangle(Channel io, Color col,
                  Float64 x1, Float64 y1,
                  Float64 x2, Float64 y2,
                  Float64 x3, Float64 y3);
void FillRect(Channel io, Color col,
              Float64 x1, Float64 y1, Float64 x2, Float64 y2);
void FillCircle(Channel io, Color col, Float64 radius,
                Float64 centerX, Float64 centerY);

// Mode (io): Draw
void DrawPoint(Channel io, Color col, Float64 x, Float64 y);
void DrawLine(Channel io, Color col,
              Float64 x1, Float64 y1, Float64 x2, Float64 y2);
void DrawTriangle(Channel io, Color col,
                  Float64 x1, Float64 y1,
                  Float64 x2, Float64 y2,
                  Float64 x3, Float64 y3);
void DrawRect(Channel io, Color col,
              Float64 x1, Float64 y1, Float64 x2, Float64 y2);
void DrawCircle(Channel io, Color col, Float64 radius,
                Float64 centerX, Float64 centerY);

// Mode (io): Draw
// Mode (sprite): Sprite
void DrawSprite(Channel io, Channel sprite,
                Float64 x, Float64 y);
void DrawSpriteTrans(Channel io, Channel sprite, Trans t,
                     Float64 x, Float64 y);

// Mode (io): Draw -> PutText >> EndDrawText >> Draw
// Mode (font): Font
void BeginDrawText(Channel io, Channel font, Color col,
                   Float64 x, Float64 y);

// Mode (io): PutText >> EndDrawText -> ()
void EndDrawText(Channel io);

// Mode (io): Draw -> Draw >> EndTransform >> Draw
void BeginTransform(Channel io, Trans t);

// Mode (io): Draw >> EndTransform -> ()
void EndTransform(Channel io);

Querying the keyboard and mouse

// Mode (io): Main
Bool IsKeyDown(Channel io, Key key);
Bool IsMouseButtonDown(Channel io, MouseButton button);
Float64 GetMouseX(Channel io);
Float64 GetMouseY(Channel io);

Simple event handling

// A 'tick' is one sixtieth of a second.

// Mode (io): Main
void WaitForTick(Channel io);
void WaitForTime(Channel io, Int32 ticks);
Key WaitForKeyPress(Channel io);

Full event handling

typedef Int32 EventTag;
enum {
  Tick,                             // Tick event
  KeyPress, KeyRepeat, KeyRelease,  // Key events
  MousePress, MouseRelease,         // Mouse button events
  MouseMove                         // Mouse move event
};

typedef struct {
  EventTag tag; // KeyPress, KeyRepeat, or KeyRelease
  Key key;
} KeyEvent;

typedef struct {
  EventTag tag; // MousePress or MouseRelease
  MouseButton button;
  Float64 x;
  Float64 y;
} MouseButtonEvent;

typedef struct {
  Float64 x;
  Float64 y;
} MouseMoveEvent;

// Mode (io):
//   Main -> TickEvent         (returns Tick)
//         | KeyEvent          (returns KeyPress, KeyRepeat,
//                                or KeyRelease)
//         | MouseButtonEvent  (returns MousePress or
//                                MouseRelease)
//         | MouseMoveEvent    (returns MouseMove)
EventTag WaitForEvent(Channel io);

// Mode (io): TickEvent -> Main
void TakeTickEvent(Channel io);

// Mode (io): KeyEvent -> Main
KeyEvent TakeKeyEvent(Channel io);

// Mode (io): MouseButtonEvent -> Main
MouseButtonEvent TakeMouseButtonEvent(Channel io);

// Mode (io): MouseMoveEvent -> Main
MouseMoveEvent TakeMouseMoveEvent(Channel io);

// Mode (io):
//   TickEvent | KeyEvent | MouseButtonEvent | MouseMoveEvent
//   -> Main
void DiscardEvent(Channel io);

Memory files

// Returns a new channel in mode 'File'.
Channel NewFile(StaticText name);

typedef Int32 StreamMode;
enum {
  Read,
  Write
};

// Mode (c):
//   File -> Read >> Close >> File   (streamMode == Read)
//         | Write >> Close >> File  (streamMode == Write)
void Open(Channel c, StreamMode streamMode);

// Mode (c): Read >> Close | Write >> Close -> ()
void Close(Channel c);

// Mode (c): Read
Int32 ReadInt32(Channel c);
Int64 ReadInt64(Channel c);
Float64 ReadFloat64(Channel c);
Bool ReadBool(Channel c);
MayTag ReadMayTag(Channel c);
ListTag ReadListTag(Channel c);

// Mode (c): Write
void WriteInt32(Channel c, Int32 x);
void WriteInt64(Channel c, Int64 x);
void WriteFloat64(Channel c, Float64 x);
void WriteBool(Channel c, Bool x);
void WriteMayTag(Channel c, MayTag tag);
void WriteListTag(Channel c, ListTag tag);

// Mode (c): File
void Clear(Channel c);

// Mode (c1, c2): File
void Swap(Channel c1, Channel c2);

Error handling

noreturn void Error(StaticText context, StaticText message);

Debugging

// This channel is in mode 'PutText'.
const Channel Trace;