Add documentation

README.md

@@ -3,25 +3,16 @@ BLC core : Core of Basic Libraries for C/C++
 
 Core functions used by almost all the projects of BLAAR
 
-It is composed of five main files for Linux and Mac OSX.
-
 - **[blc_text](include/blc_text.h)** manage ASCII terminals (colors, cursor, sizes)
 - **[blc_tools](include/blc_tools.h)** macros and functions to simplify coding and memory management
 - **[blc_mem](include/blc_mem.h)** a memory structure (data pointer and size) essentially to manage dynamic memory buffers
 - **[blc_array](include/blc_array.h)** a structure to manage n-dimensional arrays. It also manage type and format of the data
 - **[blc_realtime](include/blc_realtime.h)** few helpers to use time, POSIX semaphore and pthreads
 
-
-Install
-=======
-
-This library is installed with any configuration of blaar. However, independently of blaar, you can [manually build the library](INSTALL.md)
-
-Tutorials
-=========
-
-Exemple of simple text functions
-===============================
+Exemples
+========
+Text
+----
 
 ```c
  #include "blc_core.h"
@@ -44,15 +35,13 @@ Exemple of simple text functions
  }
 ```
 
-Exemple of text graphs
-======================
+text graphs
+-----------
 
-[image not found](t_array_1)
+![image not found](t_array_1.png)
 
 This is the output of **blc_core/t_array** see the [code](t_array/main.cpp) and the [cmake config file](t_array/CMakeLists.txt)
 
-### Manipulating **blc_array** vector
-
 You can modify the code to dynamically refresh the graph with something like:
 
 ```c++
@@ -77,8 +66,62 @@ Which produces :
 Manipulating **blc_array** 2D matrix
 ==============================
 
-[image not found](t_array_2)
+![image not found](t_array_2.png)
 
 These displays could be dynamical as well
 
+Structures
+==========
+
+blc_mem
+-------
+
+A blc_mem is a memory with a pointer of an union (i.e. a memory that can be automatically casted) and a size.
+
+    blc_mem mem(8*sizeof(float)); // Allocates 32 bytes for 8 floats
+    mem.floats[3]=4.3f; //Allocate the fourth float
+    
+The possible elements are: 
+
+    void *data; char *chars; uchar *uchars;
+    int16_t *ints16; uint16_t *uints16; 
+    int32_t *ints32; uint32_t *uints32;
+    float *floats; double *doubles;
+    
+blc_array
+---------
+
+This is a blc_mem which contains information about the structure of the data (types, format, dimensions, ...).
+
+The types are a four bytes uint32_t integer representing four ASCII chars ( comparaison are much faster and easier than char[4] ). They are used to allocate the right amount of memory for each element.
+
+    'UIN8': .uchars[i], 'INT8' .chars[i]: 1 byte
+    'UI16': .uints16[i], 'IN16' .ints16[i]: 2 bytes
+    'UI32': .uints32[i], 'IN32' .ints32[i], 'FL32' .floats[i]: 4 bytes
+    'FL64': .doubles[i] : 8 bytes 
+    
+- **format** describe how to interpret data. They follow the [fourcc](https://www.fourcc.org) convention but you can use your own format.
+
+-
+    'NDEF' : not defined (default), 
+    'TEXT', 'UTF8' : interpret as strings, 
+    'Y800' : black and white image, 'RGB3' image in RGB, 'YUV2',...
+    'LPCM' : Linear Pulse Code Modulation, sound in non compressed format, ...
+
+- **dims_nb** represent the type of strutcture: 1 for vector, 2 for matrix, 3 for cubes, ...
+
+- **dims** is an array of **blc_dim** containing the number of elements of each dim (**length**) and the **step** to use to go from one element of the dim to the next one. Usually **step** is the product of the length of the previous dimensions. For example an image 800x600 of 3 components of colors would be:
+
+-
+    dims_nb=3;
+    dims[0].length=3;
+    dims[0].step=1;
+    dims[1].length=800;
+    dims[1].step=3;
+    dims[2].length=600;
+    dims[2].step=2400; //1x3x800
+
+For the complete API use `./doc_api.sh blibs/blc_core`    
+
+