Finished porting n2DLib documentation.

doc/source/conf.py

@@ -49,8 +49,8 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Squirrel documentation'
-copyright = '2003-%s, Alberto Demichelis' % time.strftime('%Y')
-author = u'Alberto Demichelis'
+copyright = '2003-%s, Alberto Demichelis, Florian "Eiyeron" Dormont' % time.strftime('%Y')
+author = u'Alberto Demichelis, Florian "Eiyeron" Dormont'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/source/index.rst

@@ -13,6 +13,7 @@ Contents:
 
    reference/index.rst
    stdlib/index.rst
+   n2DLib/index.rst
 
 
 Indices and tables

doc/source/n2DLib/index.rst

@@ -4,7 +4,7 @@
   Squirrel N2DLib Library 
 ###########################
 
-Copyrigth (c) 2016 Florian "Eiyeron" Dormont
+Copyrigth (c) 2016 Florian "Eiyeron" Dormont, Matrefeytontias
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

doc/source/n2DLib/introduction.rst

@@ -8,5 +8,79 @@ The n2DLib library consist in a set of functions inmplemented in C. They allow a
 developper access the screen and the keybaord and offers functions to allow interacting
 with them.
 
-Thus, n2Dlib offers various functions from drawing a pixel, a sprite or circles to open
-a bitmap file to parse it and detect which key has been pressed.
+The library uses buffering to display smoothly ; that means that all drawing is done to a separate buffer in memory which is then copied to the screen.
+
+Thus, n2DLib offers various functions from drawing a pixel, a sprite or circles to open
+a bitmap file to parse it and detect which key has been pressed.
+
++++++++++++++++
+Data structures
++++++++++++++++
+
+All colors, unless specified, must be in R5G6B5 format, meaning a 16-bits number organized this way ::
+
+    Bit   | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 
+    Color | R  | R  | R  | R  | R  | G  | G | G | G | G | G | B | B | B | B | B 
+
+2DLib uses a variation on the NTI image format to store images. All images must be arrays of unsigned short organized this way ::
+
+    Entry |        0       |        1       |         2       |   3-...
+    Use   | Width in pixels|Height in pixels|Transparent color|Image data
+
+n2DLib also offers the Rect structure that has four members : `x`, `y`, `w` and `h`. You're free to use it for various purposes.
+
++++++++++++++++++++++++++
+About fixed-point numbers
++++++++++++++++++++++++++
+
+In addition to graphical commands, n2DLib offers a fast alternative to floating-point numbers that is 24.8 fixed-point numbers. Those numbers are integers whose bits 0-7 are treated like a decimal part, and whose bits 8-24 are treated like an integer part. That means 256 is actually 1.0 when used with the appropriate commands. FIxed-point angles are written in binary angles, meaning a full period is [0, 256].
+
+Since fixed-point numbers are special numbers, they can't interact normally with integers. The following array describes what you can and can't do normally :
+
++-----------+-------+-----------+
+|           |integer|fixed-point|
++-----------+-------+-----------+
+|integer    |  +-*/ |     *     |
++-----------+-------+-----------+
+|fixed-point|   */  |     +-    |
++-----------+-------+-----------+
+
+You need a special routine to :
+- add an integer to a fixed-point number
+- divide an integer by a fixed-point number
+- multiply a fixed-point number by another fixed-point number
+- divide a fixed-point number by another fixed-point number
+
+See the "Math routines" part of the doc to find how to do all of this.
+
++++++++++++++++++++++++++++++++++
+Using the key detection functions
++++++++++++++++++++++++++++++++++
+
+n2DLib provides additional key detection functions to those already provided by Ndless, and aims for full compatibility with those latters. That's why n2DLib uses Ndless's t_key struct :
+
+.. code-block:: c
+
+    typedef struct {
+        int row, col, tpad_row, tpad_col;
+        tpad_arrow_t tpad_arrow;
+    } t_key;
+
+Here's the structure seend from squirrel's side. Note that the key listing is usable with the prefix `n2dk`. Example : `n2dk.ENTER` to acces `ENTER`'s index.
+
+.. code-block:: js
+
+    local key =  {
+        row : 0, /*number*/
+        col : 0, /*number*/
+        tpad_row : 0, /*number*/
+        tpad_col : 0; /*number*/
+        tpad_arrow : 0; /*number*/
+    };
+
+
+Each key is stored depending on its position on the Nspire's keypad, row and column. You can see two different versions for each variable ; that's because the clickpad keypad and the touchpad keypad have different keymappings. This is taken care of by n2DLib internally, so you don't have to worry about it.
+
+For more info about how the keypad(s) work(s), see http://hackspire.unsads.com/wiki/index.php/Keypads .
+
+See the "Key detection functions" part of the doc to see what you can do. You don't necessarily need these routines unless you want to do specific things like custom keybinding, since what Ndless provides is enough for most cases .

doc/source/n2DLib/n2dlib.rst

@@ -0,0 +1,235 @@
+.. _n2dlib:
+
+================
+n2DLib functions
+================
+
+++++++++++++++++++++++
+Graphics
+++++++++++++++++++++++
+
+.. _n2d_clearBufferB:
+
+.. js:function:: clearBufferB()
+
+    Fills the buffer with black color.
+    
+.. _n2d_clearBufferW:
+
+.. js:function:: clearBufferW()
+
+    Fills the buffer with White color.
+    
+.. _n2d_clearBuffer:
+
+.. js:function:: clearBuffer(color)
+
+    Fills the buffer with White color.
+    
+.. _n2d_getPixel:
+
+.. js:function:: getPixel(image, x, y)
+
+    Returns the color of a given pixel in an image, or the transparent color of this image if the coordinates given are out-of-bounds.
+    
+.. _n2d_deinitBuffering:
+
+.. js:function:: deinitBuffering()
+
+    Frees memory used by the buffering functionalities. Call this as the very last instruction of your program (excepting return).
+
+.. _n2d_drawLine:
+
+.. js:function:: drawLine(x1, y1, x2, y2, color)
+
+   Draws a line between two points of the given color.
+
+.. _n2d_drawSprite:
+
+.. js:function:: drawLine(sprite, x, y, flash, flashColor)
+
+    Draws an image to the given coordinates.
+
+.. _n2d_ddrawSpritePart:
+
+.. js:function:: drawSpritePart(sprite, x, y, xp, yp, wp, hp, flash, flashColor)
+
+    Draws part of an image to the given coordinates. The routine draws what of the sprite is in the rectangle given by `xp`, `yp`, `wp` and `hp`.
+
+.. _n2d_drawSpriteRotated:
+
+.. js:function:: drawSpriteRotated(sprite, xs, ys, ws, hs, xr, yr, angle, flash, flashColor)
+
+    Draws a sprite rotated by a given angle at the coordinates given by `xs`, `ys`, `ws` and `hs` so that the rotation of the sprite is performed around the point (`xr`, `yr`), which is relative to the sprite itself. The center of the rotation will always be displayed at the coordinates (`xs`, `ys`). For example, if `xr` and `yr` are half the sprite's width and height, the sprite will be rotated around its center.
+
+.. _n2d_drawSpriteScaled:
+
+.. js:function:: drawSpriteScaled(sprite, xs, ys, ws, hs, flash, flashColor)
+
+    Draws a sprite by scaling it so that it fits perfectly in the rectangle given by `xs`, `ys`, `ws` and `hs`.
+
+.. _n2d_fillCircle:
+
+.. js:function:: fillCircle(x, y, radius, color)
+
+    Fills a circle of the given color.
+
+.. _n2d_fillEllipse:
+
+.. js:function:: fillEllipse(x, y, w, h, color)
+
+    Fills an ellipse of the given size with the given color.
+
+.. _n2d_fillRect:
+
+.. js:function:: fillRect(x, y, w, h, color)
+
+    Fills a rectangle of the given dimensions with the given color ; does clipping.
+
+.. _n2d_initBuffering:
+
+.. js:function:: initBuffering()
+
+    Initializes the buffering functionalities. Call this as the very first instruction of your program if you want to use n2DLib's buffering.
+
+.. _n2d_setPixel:
+
+.. js:function:: setPixel(x, y, color)
+
+    Sets a pixel to the given color after verifying the pixel is actually in the screen's dimensions.
+
+.. _n2d_setPixelRGB:
+
+.. js:function:: setPixelRGB(x, y, r, g, b)
+
+    Sets a pixel to the given color after verifying the pixel is actually in the screen's dimensions and using three color components.
+
+.. _n2d_setPixelUnsafe:
+
+.. js:function:: setPixelUnsafe(x, y, color)
+
+    Sets a pixel to the given color, but does not make sure the pixel is in the screen's dimensions. Faster than setPixel, but use only if you know you can't draw out of the screen.
+
+.. _n2d_updateScreen:
+
+.. js:function:: updateScreen()
+
+    Copies the content of the buffer to the screen. This does not clear the buffer.
+
+++++++++++++++++++++++
+Text routines
+++++++++++++++++++++++
+
+.. _n2d_drawChar:
+
+.. js:function:: drawChar(x, y, margin, char, fontColor, outlineColor)
+
+    Draws a single character at the given position with the given front and outline color using n2DLib's built-in font. Does clipping and supports newlines with \n. When \n is passed as ch, the function resets the X value to the passed margin value and Y goes to newline. X and Y are modified like a cursor position would and are returned in an array.
+
+.. _n2d_drawDecimal:
+
+.. js:function:: drawDecimal(x, y, number, fontColor, outlineColor)
+
+    Draws a signed integer at the given position with the given front and outline color using n2DLib's built-in font. Does clipping. X and Y are modified like a cursor position would. Use this as a fast way to display integers only.
+
+.. _n2d_drawString:
+
+.. js:function:: drawString(x, y, margin, str, fontColor, outlineColor)
+
+    Draws a string of characters at the given position with the given front and outline color using n2DLib's built-in font. Does clipping and supports newlines with \n. When \n is encountered in the string, the function resets the X value to the passed margin value and Y goes to newline. X and Y are modified like a cursor position would. Use this as a fast way to display strings only.
+
+
+.. _n2d_stringWidth:
+
+.. js:function:: stringWidth(str)
+
+    Returns the width of the string in pixels when using n2DLib's built-in font.
+
+.. _n2d_numberWitdh:
+
+.. js:function:: numberWitdh(number)
+
+    Returns the width of the decimal in pixels when drawn to the screen using n2DLib's built-in font.
+
+++++++++++++++++++++++
+Math routines
+++++++++++++++++++++++
+
+.. _n2d_fixcos:
+
+.. js:function:: fixcos(angle)
+
+    Returns the cosinus of a binary angle in fixed-point format.
+
+.. _n2d_fixdiv:
+
+.. js:function:: fixdiv(a, b)
+
+    Performs a division between two fixed-point numbers.
+
+.. _n2d_fixmul:
+
+.. js:function:: fixmul(a, b)
+
+    Performs a multiplication between two fixed-point numbers.
+
+.. _n2d_fixsin:
+
+.. js:function:: fixsin(angle)
+
+    Returns the sinus of a binary angle in fixed-point format.
+
+.. _n2d_fixtoi:
+
+.. js:function:: fixtoi(f)
+
+    Turns a fixed-point number into an integer.
+
+.. _n2d_itofix:
+
+.. js:function:: itofix(i)
+
+    Turns an integer into a fixed-point number.
+
+++++++++++++++++++++++
+Key detection routines
+++++++++++++++++++++++
+
+.. _n2d_getKeyPressed:
+
+.. js:function:: getKeyPressed(key)
+
+    Detects if any key is being pressed ; if so, returns the corresponding data. If no key is being pressed, returns the structure filled with _KEY_DUMMY and returns it.
+    
+    NOTE
+        This doesn't detect the touchpad's arrow keys.
+
+.. _n2d_isKey:
+
+.. js:function:: _n2d_isKey(key, key_index)
+
+    Returns `true` if given key match the enumeration index, or `false` if not.
+
+    USAGE
+        .. code-block:: js
+        
+            value = n2d.isKey(key, n2dk.ENTER)
+
+    NOTE
+        This is very useful for example when comparing a key that has been filled with get_key_pressed() with an Ndless `n2dk.` constant.
+
+++++++++++++++++++++++
+Image loading routines
+++++++++++++++++++++++
+
+.. _n2d_loadBMP:
+
+.. js:function:: _n2d_loadBMP(path, colorMask)
+
+    Returns a blob containing the loaded sprite with given alpha color mask if the file correctly loaded or null if it coudln't load it.
+
+    NOTE
+        This function load only 24-bit (R8G8B8) bitmap files. Make sure that you chose the correct format.
+
+    WARNING!
+        Current version of this function doesn't correctly load pictures with width not multiple of 16 (or 8). This has been issued to the library developper.