Update README.md

README.md

@@ -44,11 +44,35 @@ interface.
 
 ## how to use
 
-TODO
+For start take a look at the [helloTerminal.c](https://gitlab.com/drummyfish/small3dlib/blob/master/programs/helloTerminal.c) program. It is only a little bit more complex than a simple hello world.
+
+For more examples see the other files.
+
+The basic philosophy is:
+
+- The library implements only a rendering back-end, it doesn't perform any drawing to the actual screen,
+  hence there is no dependency on any library such as OpenGL or SDL. It just calls your front-end function
+  and tells you which pixels you should write. How you do it is up to you.
+- Before including the header, define `S3L_PIXEL_FUNCTION` to the name of a function you will use to
+  draw pixels. It is basically a fragment/pixel shader function that the library will call. You will
+  be passed info about the pixel and can decide what to do with it, so you can process it, discard it,
+  or simply write it to the screen.
+- Also define `S3L_RESOLUTION_X` and `S3L_RESOLUTION_Y` to the resolution of your rendering screen.
+- Use the provided Python tools to convert your model and textures to C arrays, include them in your
+  program and set up the scene struct.
+- Call `S3L_drawScene` on the scene to perform the frame rendering. This will cause the
+  library to start calling the `S3L_PIXEL_FUNCTION` in order to draw the frame. You can of course
+  modify the function or write a similar one of your own using the more low-level functions which are
+  also provided.
+- Fixed point arithmetics is used as a principle, but there is no abstraction above it, everything is simply
+  an integer (`S3L_Unit` type). The space is considered to be a dense grid, and what would normally be
+  a 1.0 float value is an int value equal to `S3L_FRACTIONS_PER_UNIT` units. Numbers are normalized by this
+  constant, so e.g. the sin function returns a value from `-S3L_FRACTIONS_PER_UNIT` to `S3L_FRACTIONS_PER_UNIT`.
 
 ## tips/troubleshooting
 
 - Don't forget to **compile with -O3!** This drastically improves performance.
+- In your `S3L_PIXEL_FUNC` **use a per-triangle cache!** This saves a lot of CPU time. Basically make sure you don't compute per-triangle values per-pixel, but only once, with the first pixel of the triangle. You can do this by remembering the last `triangleID` and only recompute the value when the ID changes. See the examples for how this is done.
 - Seeing buggy triangles flashing in front of the camera? With the limited 32bit arithmetic far-away things may be overflowing. Try to scale down the scene. If you also don't mind it, set `S3L_STRICT_NEAR_CULLING` to `1` -- this should probably solve it.
 - Seeing triangles disappear randomly in sorted modes? This is because the size of the memory for triangle sorting is limited by default -- increase `S3L_MAX_TRIANGLES_DRAWN`.
 - Sorted mode sorts triangles before drawing, but sometimes you need to control the drawing order more precisely. This can be done by reordering the objects in the scene list or rendering the scene multiple times without clearing the screen.