doc/index.org

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