doc/index.org

   1 #+TITLE: Sixth 3D - 3D engine
   2
   3 * (document settings) :noexport:
   4 ** use dark style for TWBS-HTML exporter
   5 #+HTML_HEAD: <link href="https://bootswatch.com/3/darkly/bootstrap.min.css" rel="stylesheet">
   6 #+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
   7 #+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js"></script>
   8 #+HTML_HEAD: <style type="text/css">
   9 #+HTML_HEAD:   footer {background-color: #111 !important;}
  10 #+HTML_HEAD:   pre {background-color: #111; color: #ccc;}
  11 #+HTML_HEAD: </style>
  12
  13 * General
  14 - This program is free software: released under Creative Commons Zero
  15   (CC0) license
  16
  17 - Program author:
  18   - Svjatoslav Agejenko
  19   - Homepage: https://svjatoslav.eu
  20   - Email: mailto://svjatoslav@svjatoslav.eu
  21
  22 - [[https://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
  23
  24 ** Source code
  25 - [[https://www2.svjatoslav.eu/gitweb/?p=sixth-3d.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
  26
  27 - [[https://www2.svjatoslav.eu/gitweb/?p=sixth-3d.git;a=summary][Browse Git repository online]]
  28
  29 - Clone Git repository using command:
  30   : git clone https://www2.svjatoslav.eu/git/sixth-3d.git
  31
  32 - See [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/][JavaDoc]].
  33
  34 * Project description
  35 + See: [[https://www3.svjatoslav.eu/projects/sixth-3d-demos/][demos of current 3D engine capabilities]]
  36
  37 [[id:d03013e5-931b-40ca-bc4b-e4b3f23b9a4e][In software]], [[id:a11f7150-1b25-4ca4-a3c3-8c8bd1352bd4][pure Java]] realtime 3D rendering engine. With the final
  38 goal of becoming a platform for buildng 3D user interfaces and
  39 interactive data visualization for [[https://www3.svjatoslav.eu/projects/sixth/][project Sixth]].
  40
  41 Sixth 3D can be also used as standalone [[id:08f71987-90af-40dc-bb65-bac87db9e652][3D engine in your project]].
  42
  43 ** Justification for software rendering
  44    :PROPERTIES:
  45    :ID:       d03013e5-931b-40ca-bc4b-e4b3f23b9a4e
  46    :END:
  47 3D rendering is done in software, 100% pure Java on CPU. At least for
  48 now. Modern CPU cores count keeps growing and therefore rendering by
  49 CPU is not as expensive as it used to be for the old single core
  50 systems.
  51
  52 CPU rendering performance is already good enough to implement usable
  53 3D UI at sufficient detail level, resolution and frame rate.
  54
  55 Also CPU rendering allows to freely test different rendering and
  56 optimization algorithms and retains complete control of every rendered
  57 pixel.
  58 ** Justification for Java
  59    :PROPERTIES:
  60    :ID:       a11f7150-1b25-4ca4-a3c3-8c8bd1352bd4
  61    :END:
  62 - It is easy to refactor and experiment with.
  63
  64 - Easy portability and installation. No need to deal with platform
  65   specific dependencies.
  66
  67 - It scales well to handle great complexity.
  68   - Allows to implement clever performance optimizations (instead of
  69     going for GPU offered brute-force rendering approach).
  70
  71 - No limitations imposed by:
  72   - requirement for decent GPU
  73   - GPU missing features
  74   - GPU missing/incomplete/buggy drivers
  75   - OpenGL specification
  76
  77 - It is fast enough thanks to:
  78   - Java virtual machine just-in-time compiler.
  79   - Growing CPU cores count.
  80
  81 - As a result it is easy to run on various hardware platforms and
  82   operating systems.
  83
  84 * API documentation
  85 - See [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/][JavaDoc]].
  86
  87 Note: due to a lack of time, there is still big room for improvement
  88 on documentation.
  89
  90 So far best resource is to download and explore source code for:
  91 + 3D engine ([[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][generated code graphs]] (generated using [[https://www3.svjatoslav.eu/projects/javainspect/][JavaInspect]]))
  92 + For API usage examples, see [[https://www3.svjatoslav.eu/projects/sixth-3d-demos/][demos]]
  93 * Instructions to embed Sixth-3D in your project
  94   :PROPERTIES:
  95   :ID:       08f71987-90af-40dc-bb65-bac87db9e652
  96   :END:
  97 Maven *pom.xml* file snippet:
  98 #+BEGIN_SRC xml
  99 <dependencies>
 100     ...
 101     <dependency>
 102         <groupId>eu.svjatoslav</groupId>
 103         <artifactId>sixth-3d</artifactId>
 104         <version>1.2</version>
 105     </dependency>
 106     ...
 107 </dependencies>
 108
 109 <repositories>
 110     ...
 111     <repository>
 112         <id>svjatoslav.eu</id>
 113         <name>Svjatoslav repository</name>
 114         <url>http://www2.svjatoslav.eu/maven/</url>
 115     </repository>
 116     ...
 117 </repositories>
 118 #+END_SRC
 119
 120 For API usage examples, see [[https://www3.svjatoslav.eu/projects/sixth-3d-demos/][demos]].
 121 * TODO features to add
 122 + read this as example, and apply improvements/fixes where applicable:
 123   http://blog.rogach.org/2015/08/how-to-create-your-own-simple-3d-render.html
 124
 125 + Partial region/frame repaint: when only one small object changed on
 126   the scene, it would be faster to re-render that specific area.
 127
 128 + Once partial rendering works, in would be easy to add multi-core
 129   rendering support. So that each core renders it's own region of the
 130   screen.
 131
 132 + Antialiazing. Would improve text readability. If antialiazing is too
 133   expensive for every frame, it could be used only for last frame
 134   before animations become still and waiting for user input starts.
 135 ** Render only visible polygons
 136 + This would significantly reduce RAM <-> CPU traffic.
 137
 138 + General algorithm description:
 139   + For each horizontal scanline:
 140     + sort polygon edges from left to right
 141     + while iterating and drawing pixels over screen X axis (left to
 142       right) track next appearing/disappearing polygons.
 143       + For each polygon edge update Z sorted active polygons list.
 144       + Only draw pixel from the top-most polygon.
 145         + Only if polygon area is transparent/half-transparent add
 146           colors from the polygons below.
 147
 148 + As a bonus, this would allow to track which polygons are really
 149   visible in the final scene for each frame.
 150
 151   + Such information allows further optimizations:
 152
 153     + Dynamic geometry simplification:
 154       + Dynamically detect and replace invisible objects from the
 155         scene with simplified bounding box.
 156
 157       + Dynamically replace boudnig box with actual object once it
 158         becomes visible.
 159
 160     + Dynamically unload unused textures from RAM.