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