Updated Image API (markdown)

Image-API.md

@@ -1,11 +1,31 @@
-This library implements its own image format for OpenComputers with a simple loseless compression algorithm. It allows you to load and save pictures in .pic format, as well as to perform simple operations like string serialization/deserialization/scaling/transforming
+This library implements its own image format for OpenComputers with a simple loseless compression algorithm. It allows you to load and save pictures in .pic format, as well as to perform simple operations like string serialization/deserialization/scaling/transforming.
 
-## Filesystem related methods
+## How does it work inside?
+
+Every image is stored in RAM as a one-dimensional table, where the first two elements are its **width** and **height**, and the next are pixel data. This approach is necessary for RAM saving. For a better understanding, I give you an table example:
+
+```lua
+{
+	160, -- Image width
+	50, -- Image height
+	
+	-- Begin of pixel data
+	0xFF0000, -- Red background color
+	0x0000FF, -- Blue symbol color,
+	0x00, -- Alpha channel,
+	"Q", -- Symbol,
+	
+	... -- Same for every pixel from left to right / top to bottom
+}
+```
+
+## Loading/saving
 
 ### image.**load**(*string* path): *table* or *boolean* result, *nil* or *string* reason
 
 Try to load an image from file system by given `path`. If loading was successful, the image table will be returned, it can be used for drawing on interface - for example, via **GUI.image**() method. If loading fails, `false` and `reason` will be returned. Reason describes why this happened - for example, the file system is read-only or there is not enough RAM to load image
 
+This method applies **24bit to 8bit** color compression and color grouping methods for better HDD usage
 ```lua
 local result, reason = image.load("test.pic")
 if result then
@@ -26,6 +46,50 @@ local success, reason = image.load("test.pic")
 if success then
   -- Image was saved
 else
- -- Image wasn't saved because of "reason"
+ -- Image wasn't saved (fs is read-only, not enough RAM or HDD free space)
 end
-```
+```
+
+## String searialization
+
+### image.**toString**(*table* image): *string* result
+
+Serializes image to string. It can be used for saving image on disk in **text** (not **binary**) format. Searialization is nearly **slow**, you **should avoid** this method if you don't really **know what you're doing**
+
+This method applies basic **24bit to 8bit** color compression, but doesn't apply color grouping compression to result, and it will be stored as linear sequence
+
+```lua
+image.toString(myImage)
+```
+```lua
+> A03200BEAA0051...
+```
+
+### image.**fromString**(*string* image): *table* result
+
+Deserializes string as picture table.
+
+```lua
+image.from("A03200BEAA0051...")
+```
+```lua
+> {
+	160,
+	50,
+	00,
+	0xDEDEDE,
+	0xBBBBBB,
+	0xFF,
+	0x00,
+	"Q",
+	...
+}
+```
+
+
+image.create(width, height, background, foreground, alpha, symbol, random)
+Create a new image of dimensions width and height. If random is true, foreground and background will be set to random colors for every pixel on the image. If random is false and if no background or foreground color is given, black color (0x000000) is automatically selected. If no alpha value is given, no alpha (0x000000) is automatically selected. If random argument is set to true, a random unicode character is selected (from character codes 65 to 90, or 'A' to 'Z') for every pixel of the image. If random is not true and ff no symbol is given, space character (' ') is automatically selected. Otherwise if random is not true and symbol is given that character will be used for the entire image.
+Returns created image
+
+image.getIndex(x, y, width)
+Returns the internal table position of a given pixel, given the xy coordinates of the target pixel and the width of the image you want pixel indexes from.