~~~~~ This program is for use of SDL with Node.js even though I did not write it as a Node.js addon because I found that too confusing. Therefore it is a C code that you must compile and then call it externally (which this package will do for you). Currently it is only working on Linux with X window system (due to the way the SDL event system works, it can't mix them with standard I/O, so instead it sends a X "client message" event when it need to control the SDL). It is similar to a terminal in a way which is why it can called SDLTERM. A few functions such as joysticks are untested because I do not have the way to test it. The export is a function (normally called SDL). The arguments are: - Width of screen - Height of screen - Depth of screen (8, 15, 16, 24, or 32) - Title (if omitted, it is "SDLTERM") - Mode (default "S_" for software rendering and no async blitting) The first character of the mode is "S" for software or "H" for hardware, and the second character can be "_" normally or "A" for async blitting. If the SDL function is called as a constructor then it creates the object, and the property called "ready" is a promise which will be resolved when when it is ready. If not called as a constructor, it returns a function, which takes as an argument a callback function, that will be called with two arguments the first being the error (if any) and the second being the SDL object that it created. There is also OpenGL mode. If the depth of the screen is "G" then OpenGL mode is activated. Functions marked ^ below are only for OpenGL, and those marked ! are not supported in OpenGL mode (but in future some may be supported even in OpenGL mode). Various objects are created by these functions. None of them can be shared between different screens! Surfaces, displays, shared memory views, sound effects, etc must be used only on the screen they are created with. Static (non-instance) properties of the SDL function itself are: SDL.ALT Mask of alt keys. SDL.CAPSLOCK Mask of caps lock keys. SDL.CTRL Mask of control keys. SDL.Icon * A symbol. However, you may set this to a string instead if you wish. It is used with the SDL.Surface.prototype.drawBobs() function. SDL.Key An object with name of SDL keys, without "SDLK_" at front. The value of these properties are the number. The first argument to keyDown and keyUp methods will be one of these key codes. SDL.META Mask of meta keys. SDL.NUMLOCK Mask of num lock keys. SDL.SHIFT Mask of shift keys. The SDL instance object has properties (* = writable): ._mem The internally mapped memory share buffer. It is best you do not touch this directly. ._send(buf) Used to send a command to the SDL instance. Normally you should not call this function yourself because it is used internally instead. The internal format of the commands to send may also differ between different implementations anyways, or different versions too possibly, so there is not really the guarantee that this will help. .clear([color]) Clear the screen, using specified colour. If not specified, colour 0 is used by default. .clip(x,y,w,h) Set the clip rectangle for blits having the screen as destination. .commonTexture(unit,func,...) ^ Create a texture, like .createTexture() or .createTexture2D(), but this new texture is read-only once created. The data is automatically filled in, given the function name (one of the properties of SDL.Common), and further arguments which are all 8-bit numbers, and their meaning depends on which function is chosen. See a section below about SDL.Common. .createDisplay() ^ Create a new display. Once the display, commands are put in then you can call .display() in order to display it. .createDrawing() Create an empty drawing for this screen. Once the drawing commands are put in, then .draw() can be called in order to draw it. .createGeometryList(offset,count,kind,vfunc,cfunc) ^ Create a new geometry list, which can then be drawn in a display using the .geometry() function in the display. The first argument is the offset into the vertex array set by setAddress(). The second argument is the number of total number of records it can contain. The third argument gives the kind of shapes to draw, which can have the same values as the .shapes() function in a display can have. The fourth argument is an array of functions to produce vertex outputs, and the fifth argument is a single function to produce the colour output. These functions can take arbitrary inputs (as long as all of them take the same number of arguments), and the vertex functions must output an array of four numbers (the X, Y, Z, and W coordinates of the vertex), while the colour function must output an array of four numbers. You must call setAddress before calling this function. .createSurface(width,height,depth,pitch,[data]) Create a off-screen surface. You are limited to 32 off-screen surfaces. Set the width, height, depth, and pitch. The depth can be 8 for a paletted picture, or can be 15 or 16 or 24 or 32 for true colours. The pitch is the number of bytes per scanline; if omitted or zero it will automatically calculate. The data is any typed array, which must be of the correct size, to initialize the contents of the surface. If the data is omitted, it will create a blank one of the correct size. The return value is the off-screen surface instance object (see below). .createTexture(unit,width,height,format,[data]) ^ Create a texture, and returns an object that can be used in a display in order to select or upload to the texture. The unit is the texture unit number; the first unit is zero and the maximum range depends on the system, but is probably at least 7. The format is one of the constants from the SDL.GL object (described elsewhere in this document): RED, RG, RGB, BGR, RGBA, or BGRA. The data is optional and is a Uint8Array that contains the pixel data; if not provided, it is blank. .createTexture2D(unit,size,format,mode,data) ^ Similar to .createTexture() but the size must be a power of two and the texture is square. The texture becomes immutable. The size parameter is the base 2 logarithm of the width or height. The mode is 0 for clamp to edge or 1 for repeating. Other parameters have the same meaning as above. This function uses the RECTANGLE target while the above function uses the 2D target. .cursor(shape) Set the mouse cursor shape. Valid numbers are 0 to 76 and 255. These are the standard X11 cursor shapes (converted into SDL format so that it is compatible with other computers too), but the number here is half of what Xlib expects. If you specify 255 then the cursor is hidden. The object SDL.Cursor maps these cursor names (without XC_ at front) to the numbers to be given to this. .depth The depth of the screen. .display(display) ^ Execute a display, and flip the screen afterward. .draw(drawing,[flip]) Draw the drawing on this screen. If flip is true then also update the picture on the screen so that the drawing is visible. If used with OpenGL, the drawing must start with a .dest() command to set the destination to a surface other than the screen; you can't draw on the screen with this function in OpenGL mode. .exposed() * Normally does nothing. If you write to it, it may be called when the window is exposed and needs to be redrawn. .filterRect(x1,y1,x2,y2) Disable mouseMove events and enables a filter rectangle. When the mouse moves out of the filter rectangle, a mouseOut event is generated and then the filter rectangle is cancelled. .flip() Call to ensure the picture on the screen is updated. You should call it after doing drawing on the screen, to ensure it is visible. .height The height of the drawable area of the screen in pixels. .joyEvent(id,itemKind,itemNumber,value1,value2) * This event has a default function which converts joystick events into keyboard events (this implementation is subject to be changed). If you override it then it won't do that conversion. Called when a joystick event occurs, where id is the number of the joystick, itemKind is the kind of control on the joystick which has been touched, itemNumber specifies which control of that kind, and value1 and value2 are the value that it has been set to. - Button (type 0): Value1 is one if pushed or zero if not pushed. Value2 is not used. - Axis (type 1): Value1 is the value of the axis as a signed 16-bit number. Normally, itemNumber 0 is the X axis and 1 is the Y axis. Value2 is not used. - Ball (type 2): Value1 is the relative X motion of the ball and value2 is the relative Y motion of the ball, both signed 16-bits. - Hat (type 3): Value1 is a bit field, where bit0 means up, bit1 means right, bit2 means down, and bit3 means left; more than one bit may be set in case of diagonals. Value2 is not used. .joyReady(id,axes,buttons,hats,balls) * Normally does nothing. If you select a joystick with joySelect then this function will be called afterward if it successfully selected it. It reports the ID number, as well as how many axes, buttons, hats, balls. .joySelect(id) Attempt to initialize joysticks and to enable events for the specified joystick ID. Which ID numbers are available is system-dependent, and how the controls are mapped to numbers is also system-dependent. It is recommended that your program allows the user to change which button has which function in your program. For menus, you should support the X and Y axis as well as the hat (if any) since different devices may map them differently. I do not know if Wii remotes will work or what will happen if one is connected, but it probably depends on the operating system (Windows will treat it differently from Linux). .keyDown(keyCode,modifier,character) * Normally does nothing. Called when a key is pushed, with the keycode (a number), the modifier codes (a number; use & with the masks to test if the modifier is pushed), and the character if applicable. The character is a string containing a single ASCII character, or an empty string if the key has no ASCII character code. .keyUp(keyCode,modifier) * Similar to keyDown but when the key is released, and no character is reported. .loadFragmentProgram(text) ^ Load a fragment program. A preprocessor is applied to allow writing fractions with a slash and to allow hex numbers with 0x at first. It returns the ID number of the program, for use in a display. The fragment program is used to determine the colour and depth of each pixel that is part of a triangle or rectangle being drawn on the screen, based on inputs that come from the vertex program or from the geometry. .loadSound(id,data,[loop]) Load a wave sound effect. (If a wave sound effect is currently playing, it will stop.) The data is a Int16Array, and is played back at 44100 Hz when you use the sound() function to tell it to play back. The id is a number in the range 0 to 32767. The loop number tells the index into the data to loop from; it is used only for music and not for sound effect. .loadVertexProgram(text) ^ Load a vertex program. A preprocessor is applied to allow writing fractions with a slash and to allow hex numbers with 0x at first. It returns the ID number of the program in order to use in a display. The vertex program is used to transform coordinates of shapes being drawn into normalized device coordinates. .mouseDown(button,x,y) * Called when mouse button is pushed. The button number is 1 for left button, 2 for middle button, and 3 for right button. .mouseMove(state,x,y) * Normally does nothing. If mouse movement events are enabled, it is called when the mouse is moved. .mouseOff() Disable mouse movement events (also cancel filter rectangle). .mouseOn() Enable mouse movement events (also cancel filter rectangle). .mouseOut() * Normally do nothing. Called once when the mouse pointer leaves the filter rectangle. .mouseUp(button,x,y) * Called when mouse button is released. .music(samples,program,pc,[nonshift]) Load and play music, where samples is an array with a list of sound numbers to map to samples for the music (you are allowed to repeat sounds in this list), program is a Buffer or Uint8Array containing the program to load, and pc is the initial value of the program counter. It will normally shift the length of the sounds, although if nonshift is specified and is true then it will not do this. .musicControl(address,value) Set a register for the music playback. The address ranges from 0 to 255 and the value ranges from 0 to 65535. .musicVolume(value) Set music volume. Range is from 0 to 32767. The useful range depends on the music being played back and on the sound effects and MML volume; if set too high it may clip. .onQuit([error]) * Normally displays an error message if an erro occurred and otherwise does nothing. You can override it and it will be called when the program is quit, possibly including the error object (if any). .palette(list,[start]) ! Set up the palette (only suitable if depth is 8). The start is the first palette index to write to (default 0), and the palette entries are numbers like "0xRRGGBB" where the R, G, B represent the red, green, blue components and each range from 0x00 to 0xFF. .pause() Pause audio playback. .play() Start or resume audio playback. .playCD([track]) Play a audio CD. If the track number is out of range or is omitted, then it will stop the playback instead. .playMML(str,interrupt) Play a MML string. It is not a standard MML but uses the same format used in MegaZeux instead. If interrupt is false then it will not play if a sound effect is already playing; if true then it interrupts the sound effect that is already playing. .quit() Cause SDL to quit. .repeat(on) Set key repeating. Can be true or false. .rgb(red,green,blue) Return the pixel value needed for the specified colour, where the red, green, blue components range from 0 to 255. This function does nothing if the depth is set to 8. For OpenGL, the format is the same as that specified for the palette. .screenInfo ! A Node.js buffer containing info for the screen format. Use this to help to create off-screen true colour surfaces. [0] Bytes per scanline (16-bits small-endian) [2] Bits per pixel [3] Bytes per pixel [4] Red channel shift amount [5] Green channel shift amount [6] Blue channel shift amount [12] Red channel mask [13] Green channel mask [14] Blue channel mask .scroll(amount,[color]) ! Scroll the area of the screen by the clip rectangle (the entire screen if no clip rectangle is set). The amount can be positive or negative, and is the number of pixels to scroll vertically. You can optionally specify the new background colour of the scrolled in part. .setAddress(vertex_size,vertex_addr,color_size,color_addr) ^ Set the vertex pointer and colour pointer for drawing shapes with OpenGL. These can be either numbers or Float32Array instances that have been returned from .viewShare() on this screen. The first and third arguments are the number of components, which can be 2 or 3 or 4 for the vertex list, and can be 3 or 4 for the colour list. If used with a geometry list then the vertex_size and color_size have to both be 4. .setCaption(text) Set the window title. (Note that the title is not necessarily visible. It depends on the window manager in use (if any).) .setMapping([id]) Set the input mapping mode (can be used to distinguish text input, game input, touch-screen, etc; the valid ID numbers depend on your program). This function currently does nothing, and you need not worry about it. Other libraries implementing the same API may use it. .share(length) Create a shared memory between the client and server. Can be used to upload OpenGL textures and vertex arrays. Should be called no more than once, and must be called before .viewShare() is usable. (The "mmap.js" dependency must be present for this function to work. It is now an optional dependency, so it is not necessarily present.) .shot(command) Take a screen shot and write it as input to the specified shell command in farbfeld format. You should then redirect output to a file, because if it writes anything to stdout that is not redirected then it will cause various problems. (Writing to stderr is OK.) (Note for OpenGL: The picture is upsidedown when OpenGL is in use. Use another program such as "ff-turn 1" to turn it back right-side up.) .sound(id,interrupt) Play a wave sound. You can tell it to interrupt or not like with MML sounds. Wave sounds and MML sounds can't play simultaneously, although either of them can be played together with background music. There is no volume control (load a quieter sound if you want it quieter). .sync(function) Calls the specified function asynchronously, with no arguments. It will not be called until all previous requests are complete. It also will not be called if SDLTERM fails before then. This function is used when synchronization with external events is needed. .text(x,y,color,text) ! Draw text at position. Uses PC character set. This is a convenience to use rather than the general drawing functions. .unclip() Unset the clip rectangle. .unloadMusic() Stop and unload background music. .unloadSound() All loaded wave sounds are unloaded from memory. .viewShare(constructor,offset,length) Returns a typed array that views part of the shared memory space. The first argument is any typed array constructor or DataView; the others are the offset into the shared memory and the length of the view. .volume(value) Set the MML volume. Range is from 0 to 32767. Does not control volume of wave souds (to do that, you must reduce the amplitude of the data before loading the sound) or music (use .musicVolume() to set that). .warp(x,y) Set the position of the mouse cursor, generating a mouse motion event. It is recommended that this should be done only in response to keyboard input, and only if keyboard commands can care about mouse position. .width The width of the drawable area of the screen in pixels. A off-screen surface object instance has properties: .clip(x,y,w,h) Set the clip rectangle for blits having this surface as destination. .colorKey([color]) If the color is null or omitted, blitting is opaque. Otherwise, pixels with the specified value are transparent for blitting. .depth The depth of this surface. .drawBobs(list) ! Draw several bobs on the screen, using this surface as source. The size of the bobs is set by the surface's clip rectangle; it also sets the position of the top-left corner of icon 0 in the surface. The list is a list of objects, each having properties "x", "y", and SDL.Icon (normally a symbol, but you may change this). The icons in the surface are then starting there and going right, reaching the next row when there is no more left on this row. .free() Free the off-screen buffer. Now it is no longer usable. Do not call any further functions on the surface after that or pass the surface to any other function after that. .height The height of this surface. .origin(x,y) Set the origin of bobs drawn from this surface. The default is 0, which means the top left corner of each bob. .palette(list,[start]) Same as the palette method for the screen object (see above), but set the palette for the surface. If the screen and surface both have depth 8 then the palette must be set to the same as the palette of the screen, but if the screen's palette is already set before the surface is created then it will automatically be set. .pitch The pitch (bytes per scanline) of this surface. .render() Render this picture onto the screen, using the clip rectangle of the screen to determine the position to write to, and the clip rectangle of this surface to determine the part to write. If OpenGL mode is used, the depth has to be 8 and the alpha and colour key are ignored. .screen The screen that this surface belongs to. You cannot share surfaces between multiple screens. .setMode(rle,[alpha]) Set the mode, where rle is boolean and if true it enables RLE accelerated blitting. If the alpha value is null or omitted then there is no alpha transparency for blitting from this surface, otherwise it will use alpha transparency, where 0 is transparent and 255 is opaque. The recommended alpha value is 128 because it is optimized. .unclip() Unset the clip rectangle. .width The width of this surface. .write(data,[x,y,w,h]) Replace part or all of the picture with the data in the specified buffer (can be a Node.js buffer or a typed array). You can specify the area of the rectangle to write into, or else it replaces the entire picture. A drawing object has methods to add shapes to the drawing (which will not be immediately visible on screen). After the function name lists L or U, where L means it can only be used if the screen is locked and U means it can only be used if the screen is unlocked; also the screen has to end up unlocked at the end of the drawing. Some functions return other functions (indicated by F); calling those functions will update the parameter of the command with the new value in this drawing. Also, the values of various registers are retained, with the exception of the source and destination surfaces, so drawing another drawing afterward will use the values that those registers ended up with if not overridden in the new drawing (but some operations will clobber the "at" and/or "from" registers). Some commands care about clipping rectangle; these are marked by C. .advanceH() Move the current position right by the current width. After a text operation the current width will be equal to the width of the text. .advanceV() Move the current position down by the current height. .at([x],[y],[w],[h]) F Set the position to draw at, as well as the width and height for the commands that use them. Omitted values are treated as zero. All values must be nonnegative. .back(color) F Set the background colour (used for text, reset, and rectPat). The depth of the current destination is considered when coding this command. .blit() U C Copy the from rectangle area from the source surface onto the destination surface. The transparency settings of the source surface are used. .blitPat() L Copy the from rectangle area from the source surface onto the destination surface. Both surfaces need to have depth 8 for this function to work properly. The current mode, pattern, and plane mask are used to copy it but the transparency settings of the source aren't used. Only where the pattern and plane mask have bits set are copied. .circle(radius) L F Draw a circle with the specified radius. .clone() Makes a copy of the current drawing and returns the copy. Changes and additions to the original will not affect the copy, and vice versa. .color(color) F Set the foreground colour. The depth of the current destination is considered when coding this command, so you can only set a 8-bit colour if the destination's depth is 8; this applies to the returned function as well. .dest([surface]) U Set the destination surface (normally the screen). Omitting the parameter or specifying null sets the destination to the screen. This is used for all drawing. .from([x],[y],[w],[h]) F Set the source rectangle for blitting. .keyName(keyCode) F Draw text (like the .text method) but the text drawn is the SDL name of the key with the specified keycode. Name is written in lowercase. .lineRel(x,y) L F Draw a line to the specified relative position from the cursor and moves the cursor to the new position. .lineTo(x,y) L F Draw a line to the specified absolute position from the cursor and moves the cursor to the new position. .lineToN(x,y) L F Draw a line to the specified absolute position from the cursor, but does not move the cursor. .lock() U Lock the surface. Needed for some operations. .mode(mode) F Set the drawing mode for blitPat and rectPat. Mode 0 is normal drawing. Mode 1 is XOR mode. Mode 2 is OR mode. Mode 3 is AND NOT mode. .opaque() Enable background opacity (currently used only for text and rectPat). .pattern(value) F Set the current pattern for blitPat and rectPat. It is a 8x4 pattern where the low bit is in the top-left corner and then follow to right. .planeMask(mask) F Set the plane mask, which is a 8-bit number. The blitPat and rectPat functions will overwrite only the bits of the destination pixel which are also set in this plane mask. Set to 255 if you want to overwrite all bits of the destination pixel. .rect() C Draw a filled rectangle with the current top, left, width, and height. .rectPat() L Draw a filled rectangle with the current top, left, width, and height. Requires the depth of the surface to be 8 for it to work properly. This function uses the current mode, pattern, and plane mask; it also uses the opacity setting. For opaque drawing, unset bits in the pattern are drawn using the background colour. For transparent drawing, unset bits in the pattern are not drawn at all. .reset(x,y) L F Draw a pixel with the background colour. Does not move cursor. .set(x,y) L F Draw a pixel with the foreground colour. Does not move cursor. .setAt(x,y,[w],[h]) L F Combines set() with at(). .source([surface]) Set the source surface for blitting from (normally the screen). Omitting or specifying null means use the screen as the source. .text(str) L F Draw the text (which uses the PC character set; only the low 8-bits of each character are used). The current width is set to the width of the text, although the cursor does not move (use advanceH to move). Also, if the returned function is called, any text will be truncated to the length of the string initially specified if the new string is longer. .transparent() Disable background opacity; background colour is not drawn and instead those pixels retain the old value. .unlock() L Unlock the surface. Needed for some operations, and make sure that the surface is unlocked when the drawing is finished, otherwise you may get an incorrect result. A display object contains a list of commands like a drawing object does, but is specific to OpenGL (the ^ is not specified since it is implied for all commands). There are beginBlock and endBlock; the commands that are not allowed inside of such a block are marked by X. .beginBlock() X Begin a block. The block executes commands normally, but may save memory and/or improve speed if the same block is executed many times. The block is internally implemented using glNewList(). You shouldn't begin a block while any display on this screen has an unfinished block. .blend(src,dst,eq) Set the source and destination blend mode. Each can be 0 or 1, or can be one of the SDL.GL constants: SRC, MINUS_SRC, ALPHA, MINUS_ALPHA, DST, or MINUS_DST. The third argument is one of the SDL.GL constants: MIN, MAX, ADD, SUBTRACT, or RSUBTRACT. Specify (ALPHA,MINUS_ALPHA,ADD) to implement alpha transparency. (Note that it will not draw at all if the depth test is failing, so if you want to blend then you may want to set the depth mode also, but the blending can also be used in order to cause the fragment program to draw into the depth buffer only.) .clear() Clear the screen (including depth buffer). The colour to use is determined by the last .clear() function of the screen; it is not saved in the display. .depthMode(mode) Set the depth test mode. It is a bit field, where bit0 means to succeed if the new value is less, bit1 means to succeed if the new value is equal, and bit2 means to succeed if the new value is greater. The fragment program outputs a depth, and if this comparison succeeds then the pixel is drawn and the depth value at that point is updated; otherwise the pixel is not drawn and the depth value is not updated. .endBlock() Ends a block; must be inside of a block to end it, and then it is no longer inside of a block. You cannot execute a display that contains an unfinished block; it may cause incorrect results if you do it anyways. .fragmentEnv(index,address) X Set an environment parameter for fragment programs. The address is a number or a Float64Array returned by the .viewShare() of the screen; it should contain four elements which form the vector value. The index is a number 0 to 7. .fragmentProgram([id]) Set the active fragment program. If id is null or omitted, disables the fragment program. The id can also be a string, in which case it loads a new fragment program (you should not do this if you intend to use the same fragment program several times in the same display or use it in multiple displays). .geometry(obj) X Execute a geometry list. .program(id) Execute a fragment program (from ID number or string) across the entire screen (taking into account the scissor box if it is enabled); the vertex program and geometry list are disabled. This is a convenience rather than using fragmentProgram and rect together. .rect(x1,y1,x2,y2) Draw a rectangle. Uses standard SDLTERM coordinates unless a vertex program is active, in which case the vertex program interprets the coordinates instead. The fragment program then determines the contents of the rectangle. .repeatBlock(id) Repeat a block. The id is the return value from a .beginBlock(). The block to repeat has to belong to the same screen as this display, but it does not necessarily have to belong to the same display. .scissor(x,y,w,h) Set the scissor rectangle. Coordinates are relative to top-left like in most other functions of SDLTERM, rather than bottom-left like OpenGL. .setTexture(texture) Select a texture. If there are multiple textures using the same texture unit number, then this command specifies which texture is active in that texture unit. .shapes(kind,start,count) X Draw shapes of the specified kind, read from the shared memory that has been configured by the screen's .setAddress() call. You can specify an offset into the vertex list to start at. The kind is one of the SDL.GL constants: POINTS, LINES, LINE_LOOP, LINE_STRIP, TRIANGLES, TRIANGLE_STRIP, or TRIANGLE_FAN. (If you want to draw other shapes (such as rectangles), make them by the combinations of triangles.) .unblend() Cancel the blending mode. .unscissor() Turn off the scissor rectangle. .update(texture,addr) X Update a texture (created with .createTexture(), not .createTexture2D()) from the shared memory at the specified address. If there are multiple textures sharing the texture unit number with that one, then the texture must be set first by .setTexture(). .vertexEnv(index,address) X Similar to .fragmentEnv() but for vertex programs. .vertexProgram([id]) Set the active vertex program. If id is null or omitted, disables the vertex program. Can also be a string, like with fragmentProgram(). A geometry list object (for use with OpenGL only) has the following properties (where * indicates read/write): .add(...) Add a record to the geometry list. The arguments needed are defined by the user when createGeometryList is called. .begin() Set length to zero and prepare to add records. .end() End the list of records. Must be called after adding records or after setting the length, before it can be displayed properly. .length * The number of entries it currently includes. .maxLength The maximum length allowed. .set(index,...) Set one entry of the geometry list by index. Does not touch the length, which you must touch yourself if you want to change it. For use with OpenGL, there is a SDL.GL object with the following constants defined: RED, RG, RGB, BGR, RGBA, BGRA, SRC, MINUS_SRC, ALPHA, MINUS_ALPHA, DST, MINUS_DST, POINTS, LINES, LINE_LOOP, LINE_STRIP, TRIANGLES, TRIANGLE_STRIP, TRIANGLE_FAN, MIN, MAX, ADD, SUBTRACT, RSUBTRACT. For use with .commonTexture(), there is a SDL.Common object with the constants defined listed below. The arguments it uses are also listed. Next to to the name is also whether the target is RECT or 2D. .PC (dir,fg_r,fg_g,fg_b,fg_a,bg_r,bg_g,bg_g,bg_a) RECT The texture contains the graphics of the 8x8 PC character set, in a vertical strip. The first argument is the direction which is 0 if the first scanline of each character is the top or 1 if it is the bottom; it always includes character 0 at the beginning of the data though. The next four arguments are the foreground colour, and the next four after that are the background colour. (The colour components are divided by 255 when being read by the fragment program.) Environment variables (must be set before SDL() is called; in most cases these should be set only by the user though rather than by the program): AUDIODEV = Set the audio device to use. SDLTERM_BUFFER = If set, overrides the buffer size for audio. The default setting is 2048. On some computers the default setting may be unsuitable. Larger numbers may cause the audio to lag more, while smaller numbers may result in underflow. SDLTERM_CD = Allow to select which drive to use to play CDs. The default value is zero, which is the default CD-ROM drive for the operating system. SDLTERM_DITHER = If set, enables dithering in OpenGL. SDLTERM_EVENTEXEC = Replaces the X event sending program with a different one. See the "events.c" source code to see what it is supposed to do. SDLTERM_EVENTSLEEP = Number of microseconds to sleep between requests; the default is 1 microsecond. Somehow this is needed to prevent protocol sequence errors. SDLTERM_EXEC = Allows using valgrind or something else to debug the program. You can specify arguments separated by spaces. SDLTERM_FULLSCREEN = Enable full screen mode. Please the program should never specify this option unless the user specifies full screen mode. SDLTERM_GAMMA = If the depth of the screen is 8, all colours in the palette are raised to this exponent. If the depth of the screen is not 8, then this environment variable does nothing. SDLTERM_GLTIME = Show time for executing a OpenGL display. Updates the window caption whenever a OpenGL display is executed. SDLTERM_KRD * = Set key repeat delay. If not set, uses default setting of SDL. Key repeat is still disabled unless the program enables it. SDLTERM_KRI * = Set key repeat interval. If not set, uses default setting of SDL instead. SDLTERM_MODE = Overrides the mode for initializing SDL. The format is the same as passed for the mode parameter of the SDL() function. SDLTERM_NODBLBUF = If set, disables OpenGL double buffering. Only suitable if OpenGL is in use. SDLTERM_NOMOUSE = If set, disable mouse input events, as well as mouse warping. (Does not currently disable changing cursor shapes, although this may change in future. If mouse grabbing is ever implemented in future, it will disable mouse grabbing too.) SDLTERM_NOSOUND * = If set, disable sound output. SDLTERM_NOSTICK = If set, disable joysticks. SDLTERM_NOWARP = If set, disable mouse warping. The program should never clear this setting; if the user does not want mouse warping, then it should remain disabled. SDLTERM_SHARE = If shared memory functions are implemented, this should be a prefix for a filename for shared memory. Should be a RAM disk. SDLTERM_TITLE = If set, uses this window caption instead of allowing it to be changed. SDL_AUDIODRIVER = Specify the audio driver to use. If set to "disk" then the audio output is written to a file. SDL_DEBUG = Enable SDL debugging messages. SDL_DISKAUDIOFILE = When "disk" audio driver is selected, specifies the filename for the audio output. SDL_DSP_NOSELECT = Causes some audio drivers to avoid use of select(). In some cases this might fix some problems, but it may also cause additional problems in some cases. SDL_JOYSTICK_DEVICE = You can tell it the device name for the joystick, to use in addition to the defaults. SDL_LINUX_JOYSTICK = On Linux system, enter a name (possibly with single quotes), number of axes, number of hats, and number of balls; use spaces in between. This overrides the auto-detection of these characteristics. SDL_NOMOUSE * = Supposed to disable mouse, but does not usually work. You can set SDLTERM_NOMOUSE instead. SDL_NO_LOCK_KEYS * = Disable SDL's special function of caps lock and num lock keys. If 1, affects both. If 2, affects caps lock only. If 3, affects num lock only. SDL_VIDEODRIVER = Currently, this program only supports the "x11" video driver (it requires the use of X11 WM events). You can contribute support for others if you wanted to. SDL_VIDEO_CENTERED = For some systems, make the window in the center of the screen. On some systems there is no window, some always center the window, some can't control centering of window, and some can use this. SDL_VIDEO_GL_DRIVER = If set and OpenGL mode is in use, then this can be used to specify the driver file for OpenGL. SDL_VIDEO_X11_NODIRECTCOLOR = If set, disables use of DirectColor visuals on X11. SDL_VIDEO_X11_VISUALID = If set, you can specify the visual to use, instead of being selected automatically. Can be decimal or can have 0x at first to be hex. SDL_WINDOWID = Use an existing window to display the picture instead of creating a new window. Normally, the program should never set any of these environment variables except the ones with asterisks, and even then, should not set them if the user has already set them. External resources: - https://raw.githubusercontent.com/infertux/SDL-1.2.7/master/include/SDL_keysym.h List of SDL keycodes - http://www.libsdl.org/release/SDL-1.2.15/docs/html/ SDL library documentation (it might not necessarily be very useful to you if you are using this JavaScript library, but maybe it is useful) - http://oss.sgi.com/projects/ogl-sample/registry/ARB/vertex_program.txt Description of the programming language used to write vertex programs. - http://oss.sgi.com/projects/ogl-sample/registry/ARB/fragment_program.txt Description of the programming language used to write fragment programs. === Music VM format === This documents the music VM. Registers (c=channel 0 to 7): 00-7F = General use (also used for stack) 80+c = Oscillator 1 frequency 88+c = Oscillator 1 sample 90+c = Oscillator 1 volume 98+c = Oscillator 1 offset A0+c = Oscillator 2 frequency A8+c = Oscillator 2 sample B0+c = Oscillator 2 volume B8+c = Oscillator 2 offset C0+c = Oscillator 3 frequency C8+c = Oscillator 3 sample D0+c = Oscillator 3 volume D8+c = Oscillator 3 offset E0+c = Channel filter E8+c = Channel mode F0+c = Old channel value F8 = Interpretive lookup table address F9 = Interpretive pointer FA = Compare value FB = Accumulator FC = Frame counter (in units of 1/44100 second) FD = Index register FE = Stack pointer FF = Program counter All registers store unsigned 16-bit numbers. All are initialized to zero, except the stack pointer is 128 and the sample numbers are 65535. The music ROM stores unsigned 8-bit numbers. Instruction opcodes have the following format: bit7-bit5 = Addressing mode bit5 = Direction (0=read 1=write) bit5-bit0 = Opcode number Addressing modes are: 000 = Register 001 = Register 010 = Register indexed 011 = Register indexed 100 = Immediate (16-bits small-endian) 101 = Accumulator 110 = Read ROM at address from register 111 = Program counter Instructions are: 00 = HLT Write value to frame counter register and halt. 01 = PSH Push to stack. 02 = JMP Write value to program counter. 03 = LDA Write value to accumulator. 04 = LDX Write value to index register. 05 = JSR Push program counter to stack and write value to program counter. 06 = ADD Add to accumulator. 07 = SUB Subtract from accumulator. 08 = ADX Add to index register. 09 = SBX Subtract from index register. 0A = MUL Multiply accumulator by value. 0B = DIV Divide accumulator by value. 0C = MOD Modulo accumulator by value. 0D = AND Bitwise AND accumulator by value. 0E = IOR Bitwise OR accumulator by value. 0F = XOR Bitwise XOR accumulator by value. 10 = LSH Left shift accumulator by value. 11 = RSH Right shift accumulator by value. 12 = TAR Low 8-bits of value is a register number; write accumulator value to that register. 13 = CMP Write value to comparison register. 14 = BEQ Write to program counter if accumulator equals compare value. 15 = BNE Write to program counter if accumulator not equals compare value. 16 = BGT Write to program counter if accumulator greater than compare value. 17 = BLT Write to program counter if accumulator less than compare value. 18 = BGE Write to program counter if accumulator greater or equal compare value. 19 = BLE Write to program counter if accumulator less or equal compare value. 1A = SMU Shifted multiply accumulator by value. 1B = RAD Read from ROM by address by register and advance register. The register to access is by low 8-bits of value. Bit15 is set for 16-bit values instead of 8-bit values. Bit14-bit8 means how much advancing. The value read is written to accumulator. 1C = LUP Increment index register, and then if new value is not equal to compare value, write the operand value to program counter. 1D = LDN If index register is nonzero, decrement it and write operand value to the program counter. 1E = BZE Write to program counter if accumulator is zero. 1F = BNZ Write to program counter if accumulator is not zero. 20 = POP Pop from stack. 21 = STA Write value of accumulator. 22 = STX Write value of index register. 23 = STZ Write zero. 24 = FRQ Write value looked up in frequency table. 25 = NXT Write value of index register plus one. 26 = BRO Get 8-bit number from ROM. 27 = WRO Get 16-bit small-endian number from ROM. 28 = XCP Copy accumulator to compare value. Write old compare value. 29 = XIN Copy accumulator to index. Write old index. 2A = INC Write value of accumulator plus one. 2B = BAR Get 8-bit number from ROM and advance. 2C = WAR Get 16-bit small-endian number from ROM and advance. 2D = DEC Write value of accumulator minus one. 2E = PRV Write value of index register minus one. 2F = INT Read one byte from ROM at interpretive pointer and advance interpretive pointer, and then look up 16-bit small-endian number using that byte as the input inside of the interpretive lookup table, and write that value. 30 = RIP Get previous byte from interpretive pointer. 31 = BIP Get byte from interpretive pointer and advance. 32 = WIP Get 16-bit small endian number from interpretive pointer and advance. 33 = XIP Copy accumulator to interpretive pointer. Write old interpret pointer. 34 = STI Write value of interpretive pointer. The channel filter register is used for filtering the output of the channel (it is a low pass filter); if zero then no filter is done, and 65535 causes the channel to always output the old value. Sample number for each oscillator can be 65535 for no oscillator. The channel mode register is defined as follows: bit10 = Oscillator 1 output bit9 = Oscillator 2 output bit8 = Oscillator 3 output bit5 = Modulation is relative to frequency bit4 = Oscillator 1 modulates oscillator 3 bit3 = Oscillator 2 modulates oscillator 3 bit2 = Oscillator 1 modulates oscillator 2 bit1 = Multiply output by oscillator 1 bit0 = Hard sync oscillator 3 by oscillator 2 Other bits are reserved and should never be set. (Later versions of SDLTERM might define their meaning, and if those bits remain clear then their meaning will be the same as the current meaning.)