doc/index.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
   5 <head>
   6 <!-- 2022-07-13 Wed 04:16 -->
   7 <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
   8 <meta name="viewport" content="width=device-width, initial-scale=1" />
   9 <title>Sixth 3D - 3D engine</title>
  10 <meta name="author" content="Svjatoslav Agejenko" />
  11 <meta name="generator" content="Org Mode" />
  12 <style>
  13   #content { max-width: 60em; margin: auto; }
  14   .title  { text-align: center;
  15              margin-bottom: .2em; }
  16   .subtitle { text-align: center;
  17               font-size: medium;
  18               font-weight: bold;
  19               margin-top:0; }
  20   .todo   { font-family: monospace; color: red; }
  21   .done   { font-family: monospace; color: green; }
  22   .priority { font-family: monospace; color: orange; }
  23   .tag    { background-color: #eee; font-family: monospace;
  24             padding: 2px; font-size: 80%; font-weight: normal; }
  25   .timestamp { color: #bebebe; }
  26   .timestamp-kwd { color: #5f9ea0; }
  27   .org-right  { margin-left: auto; margin-right: 0px;  text-align: right; }
  28   .org-left   { margin-left: 0px;  margin-right: auto; text-align: left; }
  29   .org-center { margin-left: auto; margin-right: auto; text-align: center; }
  30   .underline { text-decoration: underline; }
  31   #postamble p, #preamble p { font-size: 90%; margin: .2em; }
  32   p.verse { margin-left: 3%; }
  33   pre {
  34     border: 1px solid #e6e6e6;
  35     border-radius: 3px;
  36     background-color: #f2f2f2;
  37     padding: 8pt;
  38     font-family: monospace;
  39     overflow: auto;
  40     margin: 1.2em;
  41   }
  42   pre.src {
  43     position: relative;
  44     overflow: auto;
  45   }
  46   pre.src:before {
  47     display: none;
  48     position: absolute;
  49     top: -8px;
  50     right: 12px;
  51     padding: 3px;
  52     color: #555;
  53     background-color: #f2f2f299;
  54   }
  55   pre.src:hover:before { display: inline; margin-top: 14px;}
  56   /* Languages per Org manual */
  57   pre.src-asymptote:before { content: 'Asymptote'; }
  58   pre.src-awk:before { content: 'Awk'; }
  59   pre.src-authinfo::before { content: 'Authinfo'; }
  60   pre.src-C:before { content: 'C'; }
  61   /* pre.src-C++ doesn't work in CSS */
  62   pre.src-clojure:before { content: 'Clojure'; }
  63   pre.src-css:before { content: 'CSS'; }
  64   pre.src-D:before { content: 'D'; }
  65   pre.src-ditaa:before { content: 'ditaa'; }
  66   pre.src-dot:before { content: 'Graphviz'; }
  67   pre.src-calc:before { content: 'Emacs Calc'; }
  68   pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
  69   pre.src-fortran:before { content: 'Fortran'; }
  70   pre.src-gnuplot:before { content: 'gnuplot'; }
  71   pre.src-haskell:before { content: 'Haskell'; }
  72   pre.src-hledger:before { content: 'hledger'; }
  73   pre.src-java:before { content: 'Java'; }
  74   pre.src-js:before { content: 'Javascript'; }
  75   pre.src-latex:before { content: 'LaTeX'; }
  76   pre.src-ledger:before { content: 'Ledger'; }
  77   pre.src-lisp:before { content: 'Lisp'; }
  78   pre.src-lilypond:before { content: 'Lilypond'; }
  79   pre.src-lua:before { content: 'Lua'; }
  80   pre.src-matlab:before { content: 'MATLAB'; }
  81   pre.src-mscgen:before { content: 'Mscgen'; }
  82   pre.src-ocaml:before { content: 'Objective Caml'; }
  83   pre.src-octave:before { content: 'Octave'; }
  84   pre.src-org:before { content: 'Org mode'; }
  85   pre.src-oz:before { content: 'OZ'; }
  86   pre.src-plantuml:before { content: 'Plantuml'; }
  87   pre.src-processing:before { content: 'Processing.js'; }
  88   pre.src-python:before { content: 'Python'; }
  89   pre.src-R:before { content: 'R'; }
  90   pre.src-ruby:before { content: 'Ruby'; }
  91   pre.src-sass:before { content: 'Sass'; }
  92   pre.src-scheme:before { content: 'Scheme'; }
  93   pre.src-screen:before { content: 'Gnu Screen'; }
  94   pre.src-sed:before { content: 'Sed'; }
  95   pre.src-sh:before { content: 'shell'; }
  96   pre.src-sql:before { content: 'SQL'; }
  97   pre.src-sqlite:before { content: 'SQLite'; }
  98   /* additional languages in org.el's org-babel-load-languages alist */
  99   pre.src-forth:before { content: 'Forth'; }
 100   pre.src-io:before { content: 'IO'; }
 101   pre.src-J:before { content: 'J'; }
 102   pre.src-makefile:before { content: 'Makefile'; }
 103   pre.src-maxima:before { content: 'Maxima'; }
 104   pre.src-perl:before { content: 'Perl'; }
 105   pre.src-picolisp:before { content: 'Pico Lisp'; }
 106   pre.src-scala:before { content: 'Scala'; }
 107   pre.src-shell:before { content: 'Shell Script'; }
 108   pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
 109   /* additional language identifiers per "defun org-babel-execute"
 110        in ob-*.el */
 111   pre.src-cpp:before  { content: 'C++'; }
 112   pre.src-abc:before  { content: 'ABC'; }
 113   pre.src-coq:before  { content: 'Coq'; }
 114   pre.src-groovy:before  { content: 'Groovy'; }
 115   /* additional language identifiers from org-babel-shell-names in
 116      ob-shell.el: ob-shell is the only babel language using a lambda to put
 117      the execution function name together. */
 118   pre.src-bash:before  { content: 'bash'; }
 119   pre.src-csh:before  { content: 'csh'; }
 120   pre.src-ash:before  { content: 'ash'; }
 121   pre.src-dash:before  { content: 'dash'; }
 122   pre.src-ksh:before  { content: 'ksh'; }
 123   pre.src-mksh:before  { content: 'mksh'; }
 124   pre.src-posh:before  { content: 'posh'; }
 125   /* Additional Emacs modes also supported by the LaTeX listings package */
 126   pre.src-ada:before { content: 'Ada'; }
 127   pre.src-asm:before { content: 'Assembler'; }
 128   pre.src-caml:before { content: 'Caml'; }
 129   pre.src-delphi:before { content: 'Delphi'; }
 130   pre.src-html:before { content: 'HTML'; }
 131   pre.src-idl:before { content: 'IDL'; }
 132   pre.src-mercury:before { content: 'Mercury'; }
 133   pre.src-metapost:before { content: 'MetaPost'; }
 134   pre.src-modula-2:before { content: 'Modula-2'; }
 135   pre.src-pascal:before { content: 'Pascal'; }
 136   pre.src-ps:before { content: 'PostScript'; }
 137   pre.src-prolog:before { content: 'Prolog'; }
 138   pre.src-simula:before { content: 'Simula'; }
 139   pre.src-tcl:before { content: 'tcl'; }
 140   pre.src-tex:before { content: 'TeX'; }
 141   pre.src-plain-tex:before { content: 'Plain TeX'; }
 142   pre.src-verilog:before { content: 'Verilog'; }
 143   pre.src-vhdl:before { content: 'VHDL'; }
 144   pre.src-xml:before { content: 'XML'; }
 145   pre.src-nxml:before { content: 'XML'; }
 146   /* add a generic configuration mode; LaTeX export needs an additional
 147      (add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
 148   pre.src-conf:before { content: 'Configuration File'; }
 149
 150   table { border-collapse:collapse; }
 151   caption.t-above { caption-side: top; }
 152   caption.t-bottom { caption-side: bottom; }
 153   td, th { vertical-align:top;  }
 154   th.org-right  { text-align: center;  }
 155   th.org-left   { text-align: center;   }
 156   th.org-center { text-align: center; }
 157   td.org-right  { text-align: right;  }
 158   td.org-left   { text-align: left;   }
 159   td.org-center { text-align: center; }
 160   dt { font-weight: bold; }
 161   .footpara { display: inline; }
 162   .footdef  { margin-bottom: 1em; }
 163   .figure { padding: 1em; }
 164   .figure p { text-align: center; }
 165   .equation-container {
 166     display: table;
 167     text-align: center;
 168     width: 100%;
 169   }
 170   .equation {
 171     vertical-align: middle;
 172   }
 173   .equation-label {
 174     display: table-cell;
 175     text-align: right;
 176     vertical-align: middle;
 177   }
 178   .inlinetask {
 179     padding: 10px;
 180     border: 2px solid gray;
 181     margin: 10px;
 182     background: #ffffcc;
 183   }
 184   #org-div-home-and-up
 185    { text-align: right; font-size: 70%; white-space: nowrap; }
 186   textarea { overflow-x: auto; }
 187   .linenr { font-size: smaller }
 188   .code-highlighted { background-color: #ffff00; }
 189   .org-info-js_info-navigation { border-style: none; }
 190   #org-info-js_console-label
 191     { font-size: 10px; font-weight: bold; white-space: nowrap; }
 192   .org-info-js_search-highlight
 193     { background-color: #ffff00; color: #000000; font-weight: bold; }
 194   .org-svg { }
 195 </style>
 196 <link href="https://bootswatch.com/3/darkly/bootstrap.min.css" rel="stylesheet">
 197 <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
 198 <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js"></script>
 199 <style type="text/css">
 200 footer {background-color: #111 !important;}
 201 pre {background-color: #111; color: #ccc;}
 202 </style>
 203 <link rel="stylesheet" type="text/css" href="https://thomasf.github.io/solarized-css/solarized-dark.min.css" />
 204 </head>
 205 <body>
 206 <div id="content" class="content">
 207 <h1 class="title">Sixth 3D - 3D engine</h1>
 208 <div id="table-of-contents" role="doc-toc">
 209 <h2>Table of Contents</h2>
 210 <div id="text-table-of-contents" role="doc-toc">
 211 <ul>
 212 <li><a href="#org7511f90">1. General</a>
 213 <ul>
 214 <li><a href="#orge3f1768">1.1. Source code</a></li>
 215 </ul>
 216 </li>
 217 <li><a href="#orgfea2cd7">2. Project description</a>
 218 <ul>
 219 <li><a href="#org4103b1c">2.1. Justification for software rendering</a></li>
 220 <li><a href="#orgca70003">2.2. Justification for Java</a></li>
 221 </ul>
 222 </li>
 223 <li><a href="#org690ab91">3. API documentation</a></li>
 224 <li><a href="#org228a301">4. Instructions to embed Sixth-3D in your project</a></li>
 225 <li><a href="#org39d9f00">5. <span class="todo TODO">TODO</span> features to add</a>
 226 <ul>
 227 <li><a href="#org16a4a5d">5.1. Render only visible polygons</a></li>
 228 </ul>
 229 </li>
 230 </ul>
 231 </div>
 232 </div>
 233
 234 <div id="outline-container-org7511f90" class="outline-2">
 235 <h2 id="org7511f90"><span class="section-number-2">1.</span> General</h2>
 236 <div class="outline-text-2" id="text-1">
 237 <ul class="org-ul">
 238 <li>This program is free software: released under Creative Commons Zero
 239 (CC0) license</li>
 240
 241 <li>Program author:
 242 <ul class="org-ul">
 243 <li>Svjatoslav Agejenko</li>
 244 <li>Homepage: <a href="https://svjatoslav.eu">https://svjatoslav.eu</a></li>
 245 <li>Email: <a href="mailto://svjatoslav@svjatoslav.eu">mailto://svjatoslav@svjatoslav.eu</a></li>
 246 </ul></li>
 247
 248 <li><a href="https://www.svjatoslav.eu/projects/">Other software projects hosted at svjatoslav.eu</a></li>
 249 </ul>
 250 </div>
 251
 252 <div id="outline-container-orge3f1768" class="outline-3">
 253 <h3 id="orge3f1768"><span class="section-number-3">1.1.</span> Source code</h3>
 254 <div class="outline-text-3" id="text-1-1">
 255 <ul class="org-ul">
 256 <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></li>
 257
 258 <li><a href="https://www2.svjatoslav.eu/gitweb/?p=sixth-3d.git;a=summary">Browse Git repository online</a></li>
 259
 260 <li><p>
 261 Clone Git repository using command:
 262 </p>
 263 <pre class="example">
 264 git clone https://www2.svjatoslav.eu/git/sixth-3d.git
 265 </pre></li>
 266
 267 <li>See <a href="https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/">JavaDoc</a>.</li>
 268 </ul>
 269 </div>
 270 </div>
 271 </div>
 272
 273 <div id="outline-container-orgfea2cd7" class="outline-2">
 274 <h2 id="orgfea2cd7"><span class="section-number-2">2.</span> Project description</h2>
 275 <div class="outline-text-2" id="text-2">
 276 <ul class="org-ul">
 277 <li>See: <a href="https://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos of current 3D engine capabilities</a></li>
 278 </ul>
 279
 280 <p>
 281 <a href="#org4103b1c">In software</a>, <a href="#orgca70003">pure Java</a> realtime 3D rendering engine. With the final
 282 goal of becoming a platform for buildng 3D user interfaces and
 283 interactive data visualization for <a href="https://www3.svjatoslav.eu/projects/sixth/">project Sixth</a>.
 284 </p>
 285
 286 <p>
 287 Sixth 3D can be also used as standalone <a href="#org228a301">3D engine in your project</a>.
 288 </p>
 289 </div>
 290
 291 <div id="outline-container-org4103b1c" class="outline-3">
 292 <h3 id="org4103b1c"><span class="section-number-3">2.1.</span> Justification for software rendering</h3>
 293 <div class="outline-text-3" id="text-2-1">
 294 <p>
 295 3D rendering is done in software, 100% pure Java on CPU. At least for
 296 now. Modern CPU cores count keeps growing and therefore rendering by
 297 CPU is not as expensive as it used to be for the old single core
 298 systems.
 299 </p>
 300
 301 <p>
 302 CPU rendering performance is already good enough to implement usable
 303 3D UI at sufficient detail level, resolution and frame rate.
 304 </p>
 305
 306 <p>
 307 Also CPU rendering allows to freely test different rendering and
 308 optimization algorithms and retains complete control of every rendered
 309 pixel.
 310 </p>
 311 </div>
 312 </div>
 313 <div id="outline-container-orgca70003" class="outline-3">
 314 <h3 id="orgca70003"><span class="section-number-3">2.2.</span> Justification for Java</h3>
 315 <div class="outline-text-3" id="text-2-2">
 316 <ul class="org-ul">
 317 <li>It is easy to refactor and experiment with.</li>
 318
 319 <li>Easy portability and installation. No need to deal with platform
 320 specific dependencies.</li>
 321
 322 <li>It scales well to handle great complexity.
 323 <ul class="org-ul">
 324 <li>Allows to implement clever performance optimizations (instead of
 325 going for GPU offered brute-force rendering approach).</li>
 326 </ul></li>
 327
 328 <li>No limitations imposed by:
 329 <ul class="org-ul">
 330 <li>requirement for decent GPU</li>
 331 <li>GPU missing features</li>
 332 <li>GPU missing/incomplete/buggy drivers</li>
 333 <li>OpenGL specification</li>
 334 </ul></li>
 335
 336 <li>It is fast enough thanks to:
 337 <ul class="org-ul">
 338 <li>Java virtual machine just-in-time compiler.</li>
 339 <li>Growing CPU cores count.</li>
 340 </ul></li>
 341
 342 <li>As a result it is easy to run on various hardware platforms and
 343 operating systems.</li>
 344 </ul>
 345 </div>
 346 </div>
 347 </div>
 348
 349 <div id="outline-container-org690ab91" class="outline-2">
 350 <h2 id="org690ab91"><span class="section-number-2">3.</span> API documentation</h2>
 351 <div class="outline-text-2" id="text-3">
 352 <ul class="org-ul">
 353 <li>See <a href="https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/">JavaDoc</a>.</li>
 354 </ul>
 355
 356 <p>
 357 Note: due to a lack of time, there is still big room for improvement
 358 on documentation.
 359 </p>
 360
 361 <p>
 362 So far best resource is to download and explore source code for:
 363 </p>
 364 <ul class="org-ul">
 365 <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>))</li>
 366 <li>For API usage examples, see <a href="https://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos</a></li>
 367 </ul>
 368 </div>
 369 </div>
 370 <div id="outline-container-org228a301" class="outline-2">
 371 <h2 id="org228a301"><span class="section-number-2">4.</span> Instructions to embed Sixth-3D in your project</h2>
 372 <div class="outline-text-2" id="text-4">
 373 <p>
 374 Maven <b>pom.xml</b> file snippet:
 375 </p>
 376 <div class="org-src-container">
 377 <pre class="src src-xml">&lt;<span style="color: #A6E22E;">dependencies</span>&gt;
 378     ...
 379     &lt;<span style="color: #A6E22E;">dependency</span>&gt;
 380         &lt;<span style="color: #A6E22E;">groupId</span>&gt;eu.svjatoslav&lt;/<span style="color: #A6E22E;">groupId</span>&gt;
 381         &lt;<span style="color: #A6E22E;">artifactId</span>&gt;sixth-3d&lt;/<span style="color: #A6E22E;">artifactId</span>&gt;
 382         &lt;<span style="color: #A6E22E;">version</span>&gt;1.2&lt;/<span style="color: #A6E22E;">version</span>&gt;
 383     &lt;/<span style="color: #A6E22E;">dependency</span>&gt;
 384     ...
 385 &lt;/<span style="color: #A6E22E;">dependencies</span>&gt;
 386
 387 &lt;<span style="color: #A6E22E;">repositories</span>&gt;
 388     ...
 389     &lt;<span style="color: #A6E22E;">repository</span>&gt;
 390         &lt;<span style="color: #A6E22E;">id</span>&gt;svjatoslav.eu&lt;/<span style="color: #A6E22E;">id</span>&gt;
 391         &lt;<span style="color: #A6E22E;">name</span>&gt;Svjatoslav repository&lt;/<span style="color: #A6E22E;">name</span>&gt;
 392         &lt;<span style="color: #A6E22E;">url</span>&gt;http://www3.svjatoslav.eu/maven/&lt;/<span style="color: #A6E22E;">url</span>&gt;
 393     &lt;/<span style="color: #A6E22E;">repository</span>&gt;
 394     ...
 395 &lt;/<span style="color: #A6E22E;">repositories</span>&gt;
 396 </pre>
 397 </div>
 398
 399 <p>
 400 For API usage examples, see <a href="https://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos</a>.
 401 </p>
 402 </div>
 403 </div>
 404 <div id="outline-container-org39d9f00" class="outline-2">
 405 <h2 id="org39d9f00"><span class="section-number-2">5.</span> <span class="todo TODO">TODO</span> features to add</h2>
 406 <div class="outline-text-2" id="text-5">
 407 <ul class="org-ul">
 408 <li>read this as example, and apply improvements/fixes where applicable:
 409 <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></li>
 410
 411 <li>Improve triangulation. Read: <a href="https://ianthehenry.com/posts/delaunay/">https://ianthehenry.com/posts/delaunay/</a></li>
 412
 413 <li>Partial region/frame repaint: when only one small object changed on
 414 the scene, it would be faster to re-render that specific area.</li>
 415
 416 <li>Once partial rendering works, in would be easy to add multi-core
 417 rendering support. So that each core renders it's own region of the
 418 screen.</li>
 419
 420 <li>Antialiazing. Would improve text readability. If antialiazing is too
 421 expensive for every frame, it could be used only for last frame
 422 before animations become still and waiting for user input starts.</li>
 423 </ul>
 424 </div>
 425 <div id="outline-container-org16a4a5d" class="outline-3">
 426 <h3 id="org16a4a5d"><span class="section-number-3">5.1.</span> Render only visible polygons</h3>
 427 <div class="outline-text-3" id="text-5-1">
 428 <ul class="org-ul">
 429 <li>This would significantly reduce RAM &lt;-&gt; CPU traffic.</li>
 430
 431 <li>General algorithm description:
 432 <ul class="org-ul">
 433 <li>For each horizontal scanline:
 434 <ul class="org-ul">
 435 <li>sort polygon edges from left to right</li>
 436 <li>while iterating and drawing pixels over screen X axis (left to
 437 right) track next appearing/disappearing polygons.
 438 <ul class="org-ul">
 439 <li>For each polygon edge update Z sorted active polygons list.</li>
 440 <li>Only draw pixel from the top-most polygon.
 441 <ul class="org-ul">
 442 <li>Only if polygon area is transparent/half-transparent add
 443 colors from the polygons below.</li>
 444 </ul></li>
 445 </ul></li>
 446 </ul></li>
 447 </ul></li>
 448
 449 <li>As a bonus, this would allow to track which polygons are really
 450 visible in the final scene for each frame.
 451
 452 <ul class="org-ul">
 453 <li>Such information allows further optimizations:
 454
 455 <ul class="org-ul">
 456 <li>Dynamic geometry simplification:
 457 <ul class="org-ul">
 458 <li>Dynamically detect and replace invisible objects from the
 459 scene with simplified bounding box.</li>
 460
 461 <li>Dynamically replace boudnig box with actual object once it
 462 becomes visible.</li>
 463 </ul></li>
 464
 465 <li>Dynamically unload unused textures from RAM.</li>
 466 </ul></li>
 467 </ul></li>
 468 </ul>
 469 </div>
 470 </div>
 471 </div>
 472 </div>
 473 <div id="postamble" class="status">
 474 <p class="author">Author: Svjatoslav Agejenko</p>
 475 <p class="date">Created: 2022-07-13 Wed 04:16</p>
 476 <p class="validation"><a href="https://validator.w3.org/check?uri=referer">Validate</a></p>
 477 </div>
 478 </body>
 479 </html>