doc/index.html

   1 <!doctype html>
   2 <html lang="en">
   3 <head>
   4 <title>Sixth 3D - 3D engine</title>
   5 <!-- 2018-06-22 Fri 02:26 -->
   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/4/darkly/bootstrap.min.css" rel="stylesheet">
  11 <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
  12 <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.1/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 <hr >
 200 <ul class="org-ul">
 201 <li>This is a subproject of <a href="http://www3.svjatoslav.eu/projects/sixth/">Sixth</a>
 202 </li>
 203
 204 <li>Clone GIT repository using commanad:
 205 <pre class="example">
 206 git clone http://www2.svjatoslav.eu/git/sixth-3d.git
 207 </pre>
 208 </li>
 209
 210 <li><a href="http://www2.svjatoslav.eu/gitweb/?p=sixth-3d.git;a=snapshot;h=HEAD;sf=tgz">Download latest snapshot in TAR GZ format</a>
 211 </li>
 212
 213 <li>This program is free software: you can redistribute it and/or modify
 214 it under the terms of the <a href="https://www.gnu.org/licenses/lgpl.html">GNU Lesser General Public License</a> as
 215 published by the Free Software Foundation, either version 3 of the
 216 License, or (at your option) any later version.
 217 </li>
 218
 219 <li>Program author:
 220 <ul class="org-ul">
 221 <li>Svjatoslav Agejenko
 222 </li>
 223 <li>Homepage: <a href="http://svjatoslav.eu">http://svjatoslav.eu</a>
 224 </li>
 225 <li>Email: <a href="mailto://svjatoslav@svjatoslav.eu">mailto://svjatoslav@svjatoslav.eu</a>
 226 </li>
 227 </ul>
 228 </li>
 229
 230 <li><a href="http://www.svjatoslav.eu/projects/">Other software projects hosted at svjatoslav.eu</a>
 231 </li>
 232 </ul>
 233
 234 <div id="outline-container-sec-1" class="outline-2">
 235 <h2 id="sec-1"><span class="section-number-2">1</span> Project description</h2>
 236 <div class="outline-text-2" id="text-1">
 237 <ul class="org-ul">
 238 <li>See: <a href="http://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos of current 3D engine capabilities</a>
 239 </li>
 240 </ul>
 241
 242 <p>
 243 <a href="#sec-1-1">In software</a>, <a href="#sec-1-2">pure Java</a> realtime 3D rendering engine. With the final
 244 goal of becoming a platform for buildng 3D user interfaces and
 245 interactive data visualization for <a href="http://www3.svjatoslav.eu/projects/sixth/">project Sixth</a>.
 246 </p>
 247
 248 <p>
 249 Sixth 3D can be also used as standalone <a href="#sec-3">3D engine in your project</a>.
 250 </p>
 251 </div>
 252
 253 <div id="outline-container-sec-1-1" class="outline-3">
 254 <h3 id="sec-1-1"><a id="ID-d03013e5-931b-40ca-bc4b-e4b3f23b9a4e" name="ID-d03013e5-931b-40ca-bc4b-e4b3f23b9a4e"></a><span class="section-number-3">1.1</span> Justification for software rendering</h3>
 255 <div class="outline-text-3" id="text-1-1">
 256 <p>
 257 3D rendering is done in software, 100% pure Java on CPU. At least for
 258 now. Modern CPU cores count keeps growing and therefore rendering by
 259 CPU is not as expensive as it used to be for the old single core
 260 systems.
 261 </p>
 262
 263 <p>
 264 CPU rendering performance is already good enough to implement usable
 265 3D UI at sufficient detail level, resolution and frame rate.
 266 </p>
 267
 268 <p>
 269 Also CPU rendering allows to freely test different rendering and
 270 optimization algorithms and retains complete control of every rendered
 271 pixel.
 272 </p>
 273 </div>
 274 </div>
 275 <div id="outline-container-sec-1-2" class="outline-3">
 276 <h3 id="sec-1-2"><a id="ID-a11f7150-1b25-4ca4-a3c3-8c8bd1352bd4" name="ID-a11f7150-1b25-4ca4-a3c3-8c8bd1352bd4"></a><span class="section-number-3">1.2</span> Justification for Java</h3>
 277 <div class="outline-text-3" id="text-1-2">
 278 <ul class="org-ul">
 279 <li>It is easy to refactor and experiment with.
 280 </li>
 281
 282 <li>Easy portability and installation. No need to deal with platform
 283 specific dependencies.
 284 </li>
 285
 286 <li>It scales well to handle great complexity.
 287 <ul class="org-ul">
 288 <li>Allows to implement clever performance optimizations (instead of
 289 going for GPU offered brute-force rendering approach).
 290 </li>
 291 </ul>
 292 </li>
 293
 294 <li>No limitations imposed by:
 295 <ul class="org-ul">
 296 <li>requirement for decent GPU
 297 </li>
 298 <li>GPU missing features
 299 </li>
 300 <li>GPU missing/incomplete/buggy drivers
 301 </li>
 302 <li>OpenGL specification
 303 </li>
 304 </ul>
 305 </li>
 306
 307 <li>It is fast enough thanks to:
 308 <ul class="org-ul">
 309 <li>Java virtual machine just-in-time compiler.
 310 </li>
 311 <li>Growing CPU cores count.
 312 </li>
 313 </ul>
 314 </li>
 315
 316 <li>As a result it is easy to run on various hardware platforms and
 317 operating systems.
 318 </li>
 319 </ul>
 320 </div>
 321 </div>
 322 </div>
 323
 324 <div id="outline-container-sec-2" class="outline-2">
 325 <h2 id="sec-2"><span class="section-number-2">2</span> <span class="label label-primary TODO">TODO</span> API documentation</h2>
 326 <div class="outline-text-2" id="text-2">
 327 <p>
 328 Documentation currently missing for the lack of time.
 329 </p>
 330
 331 <p>
 332 So far best resource is to download and explore source code for:
 333 </p>
 334 <ul class="org-ul">
 335 <li>3D engine (<a href="http://www3.svjatoslav.eu/projects/sixth-3d/graphs/">generated code graphs</a> (generated using <a href="http://www3.svjatoslav.eu/projects/javainspect/">JavaInspect</a>))
 336 </li>
 337 <li>For API usage examples, see <a href="http://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos</a>
 338 </li>
 339 </ul>
 340 </div>
 341 </div>
 342 <div id="outline-container-sec-3" class="outline-2">
 343 <h2 id="sec-3"><a id="ID-08f71987-90af-40dc-bb65-bac87db9e652" name="ID-08f71987-90af-40dc-bb65-bac87db9e652"></a><span class="section-number-2">3</span> Instructions to embed Sixth-3D in your project</h2>
 344 <div class="outline-text-2" id="text-3">
 345 <p>
 346 Maven *pom.xml* file snippet:
 347 </p>
 348 <div class="org-src-container">
 349
 350 <pre class="src src-xml">&lt;dependencies&gt;
 351     ...
 352     &lt;dependency&gt;
 353         &lt;groupId&gt;eu.svjatoslav&lt;/groupId&gt;
 354         &lt;artifactId&gt;sixth-3d&lt;/artifactId&gt;
 355         &lt;version&gt;1.1&lt;/version&gt;
 356     &lt;/dependency&gt;
 357     ...
 358 &lt;/dependencies&gt;
 359
 360 &lt;repositories&gt;
 361     ...
 362     &lt;repository&gt;
 363         &lt;id&gt;svjatoslav.eu&lt;/id&gt;
 364         &lt;name&gt;Svjatoslav repository&lt;/name&gt;
 365         &lt;url&gt;http://www2.svjatoslav.eu/maven/&lt;/url&gt;
 366     &lt;/repository&gt;
 367     ...
 368 &lt;/repositories&gt;
 369 </pre>
 370 </div>
 371
 372 <p>
 373 For API usage examples, see <a href="http://www3.svjatoslav.eu/projects/sixth-3d-demos/">demos</a>.
 374 </p>
 375 </div>
 376 </div>
 377 <div id="outline-container-sec-4" class="outline-2">
 378 <h2 id="sec-4"><span class="section-number-2">4</span> <span class="label label-primary TODO">TODO</span> features to add</h2>
 379 <div class="outline-text-2" id="text-4">
 380 <ul class="org-ul">
 381 <li>Partial region/frame repaint: when only one small object changed on
 382 the scene, it would be faster to re-render that specific area.
 383 </li>
 384
 385 <li>Once partial rendering works, in would be easy to add multi-core
 386 rendering support. So that each core renders it's own region of the
 387 screen.
 388 </li>
 389
 390 <li>Antialiazing. Would improve text readability. If antialiazing is too
 391 expensive for every frame, it could be used only for last frame
 392 before animations become still and waiting for user input starts.
 393 </li>
 394
 395 <li>Render only visible polygons.
 396 <ul class="org-ul">
 397 <li>This would significantly reduce RAM &lt;-&gt; CPU traffic.
 398 </li>
 399
 400 <li>General algorithm description:
 401 <ul class="org-ul">
 402 <li>For each horizontal scanline:
 403 <ul class="org-ul">
 404 <li>sort polygon edges from left to right
 405 </li>
 406 <li>while iterating and drawing pixels over screen X axis (left to
 407 right) track next appearing/disappearing polygons.
 408 <ul class="org-ul">
 409 <li>For each polygon edge update Z sorted active polygons list.
 410 </li>
 411 <li>Only draw pixel from the top-most polygon.
 412 <ul class="org-ul">
 413 <li>Only if polygon area is transparent/half-transparent add
 414 colors from the polygons below.
 415 </li>
 416 </ul>
 417 </li>
 418 </ul>
 419 </li>
 420 </ul>
 421 </li>
 422 </ul>
 423 </li>
 424
 425 <li>As a bonus, this would allow to track which polygons are really
 426 visible in the final scene for each frame.
 427
 428 <ul class="org-ul">
 429 <li>Such information allows further optimizations:
 430
 431 <ul class="org-ul">
 432 <li>Dynamic geometry simplification:
 433 <ul class="org-ul">
 434 <li>Dynamically detect and replace invisible objects from the
 435 scene with simplified bounding box.
 436 </li>
 437
 438 <li>Dynamically replace boudnig box with actual object once it
 439 becomes visible.
 440 </li>
 441 </ul>
 442 </li>
 443
 444 <li>Dynamically unload unused textures from RAM.
 445 </li>
 446 </ul>
 447 </li>
 448 </ul>
 449 </li>
 450 </ul>
 451 </li>
 452 </ul>
 453 </div>
 454 </div>
 455 </div><div class="col-md-3"><nav id="table-of-contents">
 456 <div id="text-table-of-contents" class="bs-docs-sidebar">
 457 <ul class="nav">
 458 <li><a href="#sec-1">1. Project description</a>
 459 <ul class="nav">
 460 <li><a href="#sec-1-1">1.1. Justification for software rendering</a></li>
 461 <li><a href="#sec-1-2">1.2. Justification for Java</a></li>
 462 </ul>
 463 </li>
 464 <li><a href="#sec-2">2. API documentation</a></li>
 465 <li><a href="#sec-3">3. Instructions to embed Sixth-3D in your project</a></li>
 466 <li><a href="#sec-4">4. features to add</a></li>
 467 </ul>
 468 </div>
 469 </nav>
 470 </div></div></div>
 471 <footer id="postamble" class="">
 472 <div><p class="author">Author: Svjatoslav Agejenko</p>
 473 <p class="date">Created: 2018-06-22 Fri 02:26</p>
 474 <p class="creator"><a href="http://www.gnu.org/software/emacs/">Emacs</a> 25.1.1 (<a href="http://orgmode.org">Org-mode</a> 8.2.10)</p>
 475 </div>
 476 </footer>
 477 </body>
 478 </html>