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