Refactoring. Ability to specify look and feel for text editor.
[sixth-3d.git] / doc / index.html
1 <!doctype html>
2 <html lang="en">
3 <head>
4 <title>Sixth 3D - 3D engine</title>
5 <!-- 2021-01-10 P 01:14 -->
6 <meta charset="utf-8">
7 <meta name="viewport" content="width=device-width, initial-scale=1">
8 <meta name="generator" content="Org-mode">
9 <meta name="author" content="Svjatoslav Agejenko">
10 <link href="https://bootswatch.com/3/darkly/bootstrap.min.css" rel="stylesheet">
11 <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
12 <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js"></script>
13 <style type="text/css">
14 footer {background-color: #111 !important;}
15 pre {background-color: #111; color: #ccc;}
16 </style>
17 <style type="text/css">
18 /* org mode styles on top of twbs */
19
20 html {
21     position: relative;
22     min-height: 100%;
23 }
24
25 body {
26     font-size: 18px;
27     margin-bottom: 105px;
28 }
29
30 footer {
31     position: absolute;
32     bottom: 0;
33     width: 100%;
34     height: 101px;
35     background-color: #f5f5f5;
36 }
37
38 footer > div {
39     padding: 10px;
40 }
41
42 footer p {
43     margin: 0 0 5px;
44     text-align: center;
45     font-size: 16px;
46 }
47
48 #table-of-contents {
49     margin-top: 20px;
50     margin-bottom: 20px;
51 }
52
53 blockquote p {
54     font-size: 18px;
55 }
56
57 pre {
58     font-size: 16px;
59 }
60
61 .footpara {
62     display: inline-block;
63 }
64
65 figcaption {
66   font-size: 16px;
67   color: #666;
68   font-style: italic;
69   padding-bottom: 15px;
70 }
71
72 /* from twbs docs */
73
74 .bs-docs-sidebar.affix {
75     position: static;
76 }
77 @media (min-width: 768px) {
78     .bs-docs-sidebar {
79         padding-left: 20px;
80     }
81 }
82
83 /* All levels of nav */
84 .bs-docs-sidebar .nav > li > a {
85     display: block;
86     padding: 4px 20px;
87     font-size: 14px;
88     font-weight: 500;
89     color: #999;
90 }
91 .bs-docs-sidebar .nav > li > a:hover,
92 .bs-docs-sidebar .nav > li > a:focus {
93     padding-left: 19px;
94     color: #A1283B;
95     text-decoration: none;
96     background-color: transparent;
97     border-left: 1px solid #A1283B;
98 }
99 .bs-docs-sidebar .nav > .active > a,
100 .bs-docs-sidebar .nav > .active:hover > a,
101 .bs-docs-sidebar .nav > .active:focus > a {
102     padding-left: 18px;
103     font-weight: bold;
104     color: #A1283B;
105     background-color: transparent;
106     border-left: 2px solid #A1283B;
107 }
108
109 /* Nav: second level (shown on .active) */
110 .bs-docs-sidebar .nav .nav {
111     display: none; /* Hide by default, but at >768px, show it */
112     padding-bottom: 10px;
113 }
114 .bs-docs-sidebar .nav .nav > li > a {
115     padding-top: 1px;
116     padding-bottom: 1px;
117     padding-left: 30px;
118     font-size: 12px;
119     font-weight: normal;
120 }
121 .bs-docs-sidebar .nav .nav > li > a:hover,
122 .bs-docs-sidebar .nav .nav > li > a:focus {
123     padding-left: 29px;
124 }
125 .bs-docs-sidebar .nav .nav > .active > a,
126 .bs-docs-sidebar .nav .nav > .active:hover > a,
127 .bs-docs-sidebar .nav .nav > .active:focus > a {
128     padding-left: 28px;
129     font-weight: 500;
130 }
131
132 /* Nav: third level (shown on .active) */
133 .bs-docs-sidebar .nav .nav .nav {
134     padding-bottom: 10px;
135 }
136 .bs-docs-sidebar .nav .nav .nav > li > a {
137     padding-top: 1px;
138     padding-bottom: 1px;
139     padding-left: 40px;
140     font-size: 12px;
141     font-weight: normal;
142 }
143 .bs-docs-sidebar .nav .nav .nav > li > a:hover,
144 .bs-docs-sidebar .nav .nav .nav > li > a:focus {
145     padding-left: 39px;
146 }
147 .bs-docs-sidebar .nav .nav .nav > .active > a,
148 .bs-docs-sidebar .nav .nav .nav > .active:hover > a,
149 .bs-docs-sidebar .nav .nav .nav > .active:focus > a {
150     padding-left: 38px;
151     font-weight: 500;
152 }
153
154 /* Show and affix the side nav when space allows it */
155 @media (min-width: 992px) {
156     .bs-docs-sidebar .nav > .active > ul {
157         display: block;
158     }
159     /* Widen the fixed sidebar */
160     .bs-docs-sidebar.affix,
161     .bs-docs-sidebar.affix-bottom {
162         width: 213px;
163     }
164     .bs-docs-sidebar.affix {
165         position: fixed; /* Undo the static from mobile first approach */
166         top: 20px;
167     }
168     .bs-docs-sidebar.affix-bottom {
169         position: absolute; /* Undo the static from mobile first approach */
170     }
171     .bs-docs-sidebar.affix .bs-docs-sidenav,.bs-docs-sidebar.affix-bottom .bs-docs-sidenav {
172         margin-top: 0;
173         margin-bottom: 0
174     }
175 }
176 @media (min-width: 1200px) {
177     /* Widen the fixed sidebar again */
178     .bs-docs-sidebar.affix-bottom,
179     .bs-docs-sidebar.affix {
180         width: 263px;
181     }
182 }
183 </style>
184 <script type="text/javascript">
185 $(function() {
186     'use strict';
187
188     $('.bs-docs-sidebar li').first().addClass('active');
189
190     $(document.body).scrollspy({target: '.bs-docs-sidebar'});
191
192     $('.bs-docs-sidebar').affix();
193 });
194 </script>
195 </head>
196 <body>
197 <div id="content" class="container">
198 <div class="row"><div class="col-md-9"><h1 class="title">Sixth 3D - 3D engine</h1>
199
200 <div id="outline-container-sec-1" class="outline-2">
201 <h2 id="sec-1"><span class="section-number-2">1</span> General</h2>
202 <div class="outline-text-2" id="text-1">
203 <ul class="org-ul">
204 <li>This program is free software: released under Creative Commons Zero
205 (CC0) license
206 </li>
207
208 <li>Program author:
209 <ul class="org-ul">
210 <li>Svjatoslav Agejenko
211 </li>
212 <li>Homepage: <a href="https://svjatoslav.eu">https://svjatoslav.eu</a>
213 </li>
214 <li>Email: <a href="mailto://svjatoslav@svjatoslav.eu">mailto://svjatoslav@svjatoslav.eu</a>
215 </li>
216 </ul>
217 </li>
218
219 <li><a href="https://www.svjatoslav.eu/projects/">Other software projects hosted at svjatoslav.eu</a>
220 </li>
221 </ul>
222 </div>
223
224 <div id="outline-container-sec-1-1" class="outline-3">
225 <h3 id="sec-1-1"><span class="section-number-3">1.1</span> Source code</h3>
226 <div class="outline-text-3" id="text-1-1">
227 <ul class="org-ul">
228 <li><a href="https://www2.svjatoslav.eu/gitweb/?p=sixth-3d.git;a=snapshot;h=HEAD;sf=tgz">Download latest snapshot in TAR GZ format</a>
229 </li>
230
231 <li><a href="https://www2.svjatoslav.eu/gitweb/?p=sixth-3d.git;a=summary">Browse Git repository online</a>
232 </li>
233
234 <li>Clone Git repository using command:
235 <pre class="example">
236 git clone https://www2.svjatoslav.eu/git/sixth-3d.git
237
238 </pre>
239 </li>
240
241 <li>See <a href="https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/">JavaDoc</a>.
242 </li>
243 </ul>
244 </div>
245 </div>
246 </div>
247
248 <div id="outline-container-sec-2" class="outline-2">
249 <h2 id="sec-2"><span class="section-number-2">2</span> Project description</h2>
250 <div class="outline-text-2" id="text-2">
251 <ul class="org-ul">
252 <li>See: <a href="https://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos of current 3D engine capabilities</a>
253 </li>
254 </ul>
255
256 <p>
257 <a href="#sec-2-1">In software</a>, <a href="#sec-2-2">pure Java</a> realtime 3D rendering engine. With the final
258 goal of becoming a platform for buildng 3D user interfaces and
259 interactive data visualization for <a href="https://www3.svjatoslav.eu/projects/sixth/">project Sixth</a>.
260 </p>
261
262 <p>
263 Sixth 3D can be also used as standalone <a href="#sec-4">3D engine in your project</a>.
264 </p>
265 </div>
266
267 <div id="outline-container-sec-2-1" class="outline-3">
268 <h3 id="sec-2-1"><a id="ID-d03013e5-931b-40ca-bc4b-e4b3f23b9a4e" name="ID-d03013e5-931b-40ca-bc4b-e4b3f23b9a4e"></a><span class="section-number-3">2.1</span> Justification for software rendering</h3>
269 <div class="outline-text-3" id="text-2-1">
270 <p>
271 3D rendering is done in software, 100% pure Java on CPU. At least for
272 now. Modern CPU cores count keeps growing and therefore rendering by
273 CPU is not as expensive as it used to be for the old single core
274 systems.
275 </p>
276
277 <p>
278 CPU rendering performance is already good enough to implement usable
279 3D UI at sufficient detail level, resolution and frame rate.
280 </p>
281
282 <p>
283 Also CPU rendering allows to freely test different rendering and
284 optimization algorithms and retains complete control of every rendered
285 pixel.
286 </p>
287 </div>
288 </div>
289 <div id="outline-container-sec-2-2" class="outline-3">
290 <h3 id="sec-2-2"><a id="ID-a11f7150-1b25-4ca4-a3c3-8c8bd1352bd4" name="ID-a11f7150-1b25-4ca4-a3c3-8c8bd1352bd4"></a><span class="section-number-3">2.2</span> Justification for Java</h3>
291 <div class="outline-text-3" id="text-2-2">
292 <ul class="org-ul">
293 <li>It is easy to refactor and experiment with.
294 </li>
295
296 <li>Easy portability and installation. No need to deal with platform
297 specific dependencies.
298 </li>
299
300 <li>It scales well to handle great complexity.
301 <ul class="org-ul">
302 <li>Allows to implement clever performance optimizations (instead of
303 going for GPU offered brute-force rendering approach).
304 </li>
305 </ul>
306 </li>
307
308 <li>No limitations imposed by:
309 <ul class="org-ul">
310 <li>requirement for decent GPU
311 </li>
312 <li>GPU missing features
313 </li>
314 <li>GPU missing/incomplete/buggy drivers
315 </li>
316 <li>OpenGL specification
317 </li>
318 </ul>
319 </li>
320
321 <li>It is fast enough thanks to:
322 <ul class="org-ul">
323 <li>Java virtual machine just-in-time compiler.
324 </li>
325 <li>Growing CPU cores count.
326 </li>
327 </ul>
328 </li>
329
330 <li>As a result it is easy to run on various hardware platforms and
331 operating systems.
332 </li>
333 </ul>
334 </div>
335 </div>
336 </div>
337
338 <div id="outline-container-sec-3" class="outline-2">
339 <h2 id="sec-3"><span class="section-number-2">3</span> API documentation</h2>
340 <div class="outline-text-2" id="text-3">
341 <ul class="org-ul">
342 <li>See <a href="https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/">JavaDoc</a>.
343 </li>
344 </ul>
345
346 <p>
347 Note: due to a lack of time, there is still big room for improvement
348 on documentation.
349 </p>
350
351 <p>
352 So far best resource is to download and explore source code for:
353 </p>
354 <ul class="org-ul">
355 <li>3D engine (<a href="https://www3.svjatoslav.eu/projects/sixth-3d/graphs/">generated code graphs</a> (generated using <a href="https://www3.svjatoslav.eu/projects/javainspect/">JavaInspect</a>))
356 </li>
357 <li>For API usage examples, see <a href="https://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos</a>
358 </li>
359 </ul>
360 </div>
361 </div>
362 <div id="outline-container-sec-4" class="outline-2">
363 <h2 id="sec-4"><a id="ID-08f71987-90af-40dc-bb65-bac87db9e652" name="ID-08f71987-90af-40dc-bb65-bac87db9e652"></a><span class="section-number-2">4</span> Instructions to embed Sixth-3D in your project</h2>
364 <div class="outline-text-2" id="text-4">
365 <p>
366 Maven <b>pom.xml</b> file snippet:
367 </p>
368 <div class="org-src-container">
369
370 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">dependencies</span>&gt;
371     ...
372     &lt;<span style="color: #A6E22E;">dependency</span>&gt;
373         &lt;<span style="color: #A6E22E;">groupId</span>&gt;eu.svjatoslav&lt;/<span style="color: #A6E22E;">groupId</span>&gt;
374         &lt;<span style="color: #A6E22E;">artifactId</span>&gt;sixth-3d&lt;/<span style="color: #A6E22E;">artifactId</span>&gt;
375         &lt;<span style="color: #A6E22E;">version</span>&gt;1.2&lt;/<span style="color: #A6E22E;">version</span>&gt;
376     &lt;/<span style="color: #A6E22E;">dependency</span>&gt;
377     ...
378 &lt;/<span style="color: #A6E22E;">dependencies</span>&gt;
379
380 &lt;<span style="color: #A6E22E;">repositories</span>&gt;
381     ...
382     &lt;<span style="color: #A6E22E;">repository</span>&gt;
383         &lt;<span style="color: #A6E22E;">id</span>&gt;svjatoslav.eu&lt;/<span style="color: #A6E22E;">id</span>&gt;
384         &lt;<span style="color: #A6E22E;">name</span>&gt;Svjatoslav repository&lt;/<span style="color: #A6E22E;">name</span>&gt;
385         &lt;<span style="color: #A6E22E;">url</span>&gt;http://www2.svjatoslav.eu/maven/&lt;/<span style="color: #A6E22E;">url</span>&gt;
386     &lt;/<span style="color: #A6E22E;">repository</span>&gt;
387     ...
388 &lt;/<span style="color: #A6E22E;">repositories</span>&gt;
389 </pre>
390 </div>
391
392 <p>
393 For API usage examples, see <a href="https://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos</a>.
394 </p>
395 </div>
396 </div>
397 <div id="outline-container-sec-5" class="outline-2">
398 <h2 id="sec-5"><span class="section-number-2">5</span> <span class="label label-primary TODO">TODO</span> features to add</h2>
399 <div class="outline-text-2" id="text-5">
400 <ul class="org-ul">
401 <li>read this as example, and apply improvements/fixes where applicable:
402 <a href="http://blog.rogach.org/2015/08/how-to-create-your-own-simple-3d-render.html">http://blog.rogach.org/2015/08/how-to-create-your-own-simple-3d-render.html</a>
403 </li>
404
405 <li>Partial region/frame repaint: when only one small object changed on
406 the scene, it would be faster to re-render that specific area.
407 </li>
408
409 <li>Once partial rendering works, in would be easy to add multi-core
410 rendering support. So that each core renders it's own region of the
411 screen.
412 </li>
413
414 <li>Antialiazing. Would improve text readability. If antialiazing is too
415 expensive for every frame, it could be used only for last frame
416 before animations become still and waiting for user input starts.
417 </li>
418 </ul>
419 </div>
420 <div id="outline-container-sec-5-1" class="outline-3">
421 <h3 id="sec-5-1"><span class="section-number-3">5.1</span> Render only visible polygons</h3>
422 <div class="outline-text-3" id="text-5-1">
423 <ul class="org-ul">
424 <li>This would significantly reduce RAM &lt;-&gt; CPU traffic.
425 </li>
426
427 <li>General algorithm description:
428 <ul class="org-ul">
429 <li>For each horizontal scanline:
430 <ul class="org-ul">
431 <li>sort polygon edges from left to right
432 </li>
433 <li>while iterating and drawing pixels over screen X axis (left to
434 right) track next appearing/disappearing polygons.
435 <ul class="org-ul">
436 <li>For each polygon edge update Z sorted active polygons list.
437 </li>
438 <li>Only draw pixel from the top-most polygon.
439 <ul class="org-ul">
440 <li>Only if polygon area is transparent/half-transparent add
441 colors from the polygons below.
442 </li>
443 </ul>
444 </li>
445 </ul>
446 </li>
447 </ul>
448 </li>
449 </ul>
450 </li>
451
452 <li>As a bonus, this would allow to track which polygons are really
453 visible in the final scene for each frame.
454
455 <ul class="org-ul">
456 <li>Such information allows further optimizations:
457
458 <ul class="org-ul">
459 <li>Dynamic geometry simplification:
460 <ul class="org-ul">
461 <li>Dynamically detect and replace invisible objects from the
462 scene with simplified bounding box.
463 </li>
464
465 <li>Dynamically replace boudnig box with actual object once it
466 becomes visible.
467 </li>
468 </ul>
469 </li>
470
471 <li>Dynamically unload unused textures from RAM.
472 </li>
473 </ul>
474 </li>
475 </ul>
476 </li>
477 </ul>
478 </div>
479 </div>
480 </div>
481 </div><div class="col-md-3"><nav id="table-of-contents">
482 <div id="text-table-of-contents" class="bs-docs-sidebar">
483 <ul class="nav">
484 <li><a href="#sec-1">1. General</a>
485 <ul class="nav">
486 <li><a href="#sec-1-1">1.1. Source code</a></li>
487 </ul>
488 </li>
489 <li><a href="#sec-2">2. Project description</a>
490 <ul class="nav">
491 <li><a href="#sec-2-1">2.1. Justification for software rendering</a></li>
492 <li><a href="#sec-2-2">2.2. Justification for Java</a></li>
493 </ul>
494 </li>
495 <li><a href="#sec-3">3. API documentation</a></li>
496 <li><a href="#sec-4">4. Instructions to embed Sixth-3D in your project</a></li>
497 <li><a href="#sec-5">5. features to add</a>
498 <ul class="nav">
499 <li><a href="#sec-5-1">5.1. Render only visible polygons</a></li>
500 </ul>
501 </li>
502 </ul>
503 </div>
504 </nav>
505 </div></div></div>
506 <footer id="postamble" class="">
507 <div><p class="author">Author: Svjatoslav Agejenko</p>
508 <p class="date">Created: 2021-01-10 P 01:14</p>
509 <p class="creator"><a href="http://www.gnu.org/software/emacs/">Emacs</a> 26.1 (<a href="http://orgmode.org">Org-mode</a> 9.1.9)</p>
510 </div>
511 </footer>
512 </body>
513 </html>