doc/index.org

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