README.md

   1 # raycastlib
   2
   3 Ray casting library for (not only) limited-resource computers.
   4
   5 If you like this, you may also like my similar project: [small3dlib](https://gitlab.com/drummyfish/small3dlib).
   6
   7 eye-candy previews
   8 ------------------
   9
  10 Pokitto (32bit embedded console, 48 MHz, 36 kB RAM):
  11
  12 ![](/media/pokitto1.gif)
  13 ![](/media/pokitto2.gif)
  14 ![](/media/pokitto3.gif)
  15
  16 SDL (PC):
  17
  18 ![](/media/sdl.gif)
  19
  20 Arduboy (8bit Arduino console, 16 MHz, 2.5 kB RAM):
  21
  22 ![](/media/arduboy.gif)
  23 ![](/media/arduboy2.gif)
  24
  25 terminal:
  26
  27 ![](/media/terminal.gif)
  28
  29 Gamebuino META (Arduino 32bit console, 48 MHz, 32 kB RAM):
  30
  31 ![](/media/gamebuino.gif)
  32
  33 features
  34 --------
  35
  36 - Very fast, small and efficient.
  37 - Uses only integer math (32bit).
  38 - No dependencies (uses only stdint standard library), extremely portable.
  39 - Single header, KISS.
  40 - Advanced rendering of variable height floor and ceiling.
  41 - Textured walls and floor.
  42 - Depth information (e.g. for fog or z-buffer rendering).
  43 - Camera shearing (looking up/down).
  44 - Camera movement with collisions.
  45 - Partial support for opening door.
  46 - Pure C99, tested to run as C++ as well.
  47 - Optional framework functions that handle the whole rendering.
  48 - Still flexible -- pixels are left for you to draw in any way you want.
  49 - Tested on multiple platforms (PC, Arduboy, Pokitto, Gamebuino META).
  50 - Many compile-time options to tune the performance vs quality.
  51 - Well commented and formatted code.
  52 - Completely free of legal restrictions, do literally anything you want.
  53
  54 **NOTE**: Backwards compatibility isn't a goal of this libraray. It is meant to
  55 be an as-is set of tools that the users is welcome to adjust for their
  56 specific project. So new features will be preferred to keeping the same
  57 interface.
  58
  59 how to use
  60 ----------
  61
  62 For start take a look at the [testTerminal.c](https://gitlab.com/drummyfish/raycastlib/blob/master/programs/testTerminal.c) program.
  63 It is only a little bit more complex than a simple hello world.
  64
  65 For more examples see the other files, plus my [Pokitto demos](https://gitlab.com/drummyfish/Pokitto-Raycasting) repository,
  66 which contains some better documented example code, including a [very simple hello world](https://gitlab.com/drummyfish/Pokitto-Raycasting/blob/master/helloRay.cpp).
  67
  68 The basic philosophy is:
  69
  70 - The library implements only a rendering back-end, it doesn't permorm any drawing to the actual screen,
  71   hence there is no dependency on any library such as OpenGL or SDL. It just calls your front-end function
  72   and tells you which pixels you should write. How you do it is up to you.
  73 - Before including the header, define `RCL_PIXEL_FUNCTION` to the name of a function you will use to
  74   draw pixels. It is basically a fragment/pixel shader function that the library will call. You will
  75   be passed info about the pixel and can decide what to do with it, so you can process it, discard it,
  76   or simply write it to the screen.
  77 - Call `RCL_renderSimple` or `RCL_renderComplex` to perform the frame rendering. This will cause the
  78   library to start calling the `RCL_PIXEL_FUNCTION` in order to draw the frame. You can optionally write
  79   a similar function of your own using the more low-level functions which are also provided.
  80 - The library gets info about the world (such as floor or ceiling height) via *array* functions
  81   (`RCL_ArrayFunction` type) -- functions that take *x* and *y* coordinates of a square and return given
  82   information. This way you are free to not only fetch the map data from an array, but also generate
  83   the world procedurally if that is what you want.
  84 - Fixed point arithmetics is used as a principle, but there is no abstraction above it, everything is simply
  85   an integer (`RCL_Unit` type). The space is considered to be a dense grid, where each world square
  86   has a side length of `RCL_UNITS_PER_SQUARE` units. Numbers are normalized by this constant, so e.g.
  87   the sin function returns a value from `-RCL_UNITS_PER_SQUARE` to `RCL_UNITS_PER_SQUARE`.
  88
  89 TODO
  90 ----
  91
  92 - Transparency (conditional ray passing through).
  93 - Doors in the middle of squares.
  94 - Rolling doors for `RCL_renderComplex`.
  95 - Possibly merge all rendering functions into one.
  96
  97 license
  98 -------
  99
 100 Everything is CC0 1.0 + a waiver of all other IP rights (including patents). The art used in demos is either my own released nder CC0 or someone else's released under CC0.
 101
 102 Please support free software and free culture by using free licenses and/or waivers.
 103
 104 If you'd like to support me or just read something about me and my projects, visit my site: [www.tastyfish.cz](http://www.tastyfish.cz/).