From: Svjatoslav Agejenko Date: Tue, 14 Apr 2026 21:24:33 +0000 (+0300) Subject: docs: overhaul SVG diagrams and add style guide X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=d325ca5c27264d4cffdb246d14d871d12555d03d;p=sixth-3d.git docs: overhaul SVG diagrams and add style guide - Scale all SVG diagrams to larger dimensions (640x480/640x520) for improved visibility - Enhance shading diagrams with detailed annotations: Lambert cosine law angle examples, ambient light comparison panels, distance attenuation curve plot - Create doc/style.css and link from all pages to consolidate shared SVG theme and responsive media styles - Remove completed TODO item for coordinate system diagram - Fix internal link in index.org to use simpler anchor syntax --- diff --git a/TODO.org b/TODO.org index ca72dc7..2eab58f 100644 --- a/TODO.org +++ b/TODO.org @@ -2,12 +2,6 @@ :PROPERTIES: :CUSTOM_ID: documentation :END: -** Clarify axis orientation (X, Y, Z) for AI assistants and developers -:PROPERTIES: -:CUSTOM_ID: clarify-axis-orientation -:END: -Add a coordinate system diagram to the documentation. - ** Document shading Make separate demo about that with shaded spheres and some light diff --git a/doc/coordinate-system.svg b/doc/coordinate-system.svg index 2a7eccb..4497bf3 100644 --- a/doc/coordinate-system.svg +++ b/doc/coordinate-system.svg @@ -1,18 +1,18 @@ - - - - - - X - right (+) / left (-) - - - Y - down (+) / up (-) - - - Z - away (+) / towards (-) - Origin - (0, 0, 0) + + + + + + X + right (+) / left (-) + + + Y + down (+) / up (-) + + + Z + away (+) / towards (-) + Origin + (0, 0, 0) \ No newline at end of file diff --git a/doc/csg/index.org b/doc/csg/index.org index b128990..9428c94 100644 --- a/doc/csg/index.org +++ b/doc/csg/index.org @@ -8,39 +8,7 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil -#+begin_export html - -#+end_export +#+HTML_HEAD: [[file:../index.org][Back to main documentation]] diff --git a/doc/edge.svg b/doc/edge.svg index 3ef023e..e9af1cf 100644 --- a/doc/edge.svg +++ b/doc/edge.svg @@ -1,12 +1,12 @@ - - - - - - - - V₁ - V₂ - V₃ - edge + + + + + + + + V₁ + V₂ + V₃ + edge diff --git a/doc/face-triangle.svg b/doc/face-triangle.svg index 8e8eb13..509c841 100644 --- a/doc/face-triangle.svg +++ b/doc/face-triangle.svg @@ -1,14 +1,14 @@ - - - - - - - - - - V₁ - V₂ - V₃ - FACE + + + + + + + + + + V₁ + V₂ + V₃ + FACE diff --git a/doc/frustum-culling/index.org b/doc/frustum-culling/index.org index 9bd15aa..b349228 100644 --- a/doc/frustum-culling/index.org +++ b/doc/frustum-culling/index.org @@ -8,39 +8,7 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil -#+begin_export html - -#+end_export +#+HTML_HEAD: [[file:../index.org][Back to main documentation]] diff --git a/doc/index.org b/doc/index.org index 181fc4f..0043675 100644 --- a/doc/index.org +++ b/doc/index.org @@ -8,57 +8,7 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil -#+begin_export html - -#+end_export - +#+HTML_HEAD: * Introduction :PROPERTIES: @@ -139,7 +89,7 @@ Also add the repository (the library is not on Maven Central): [[https://www3.svjatoslav.eu/projects/sixth-3d-demos/#minimal-example][minimal example]] to see the basic boilerplate needed to render a 3D scene. -- Study how [[id:4b6c1355-0afe-40c6-86c3-14bf8a11a8d0][Sixth 3D engine]] works. +- Study [[#defining-scene][how Sixth 3D engine works]]. - Read online [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/][JavaDoc]]. - See [[https://www3.svjatoslav.eu/projects/sixth-3d/graphs/][*Sixth 3D* class diagrams]]. (Diagrams were generated by using [[https://www3.svjatoslav.eu/projects/javainspect/][JavaInspect]] utility) diff --git a/doc/mesh.svg b/doc/mesh.svg index fcca520..8a20f46 100644 --- a/doc/mesh.svg +++ b/doc/mesh.svg @@ -1,22 +1,22 @@ - - - - - - - - - - - - - - - - - - - triangulated - section - + + + + + + + + + + + + + + + + + + + triangulated + section + diff --git a/doc/normal-vector.svg b/doc/normal-vector.svg index ce8aaa1..016136e 100644 --- a/doc/normal-vector.svg +++ b/doc/normal-vector.svg @@ -1,18 +1,18 @@ - - - - - - - - - N̂ - unit normal - (perpendicular - to surface) - - - Light - - L · N = brightness + + + + + + + + + N̂ + unit normal + (perpendicular + to surface) + + + Light + + L · N = brightness diff --git a/doc/perspective-correct-textures/index.org b/doc/perspective-correct-textures/index.org index a2787ef..1aa4bf8 100644 --- a/doc/perspective-correct-textures/index.org +++ b/doc/perspective-correct-textures/index.org @@ -8,39 +8,7 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil -#+begin_export html - -#+end_export +#+HTML_HEAD: [[file:../index.org][Back to main documentation]] diff --git a/doc/point3d-vertex.svg b/doc/point3d-vertex.svg index a3e0d16..0954bac 100644 --- a/doc/point3d-vertex.svg +++ b/doc/point3d-vertex.svg @@ -1,5 +1,5 @@ - - + + diff --git a/doc/rendering-loop/index.org b/doc/rendering-loop/index.org index 1da5809..b671ad2 100644 --- a/doc/rendering-loop/index.org +++ b/doc/rendering-loop/index.org @@ -8,22 +8,7 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil -#+begin_export html - -#+end_export +#+HTML_HEAD: [[file:../index.org][Back to main documentation]] diff --git a/doc/shading/ambient-light-comparison.svg b/doc/shading/ambient-light-comparison.svg index 9e2f058..ce07a00 100644 --- a/doc/shading/ambient-light-comparison.svg +++ b/doc/shading/ambient-light-comparison.svg @@ -1,21 +1,51 @@ - - + + + + + - - - no ambient - (pure black) +Ambient Light +base illumination applied to all surfaces equally, regardless of orientation - - → + + + + + - - - ambient - + + + + + + + +Color(0, 0, 0) +✗ pure black +harsh shadows, no depth - - ambient provides base illumination - + + + + + + + +Color(50, 50, 50) +✓ balanced +depth preserved + + + + + + + + +Color(150, 150, 150) +✗ too flat +no depth contrast + + +lightingManager.setAmbientLight(new Color(50, 50, 50)) ← default + \ No newline at end of file diff --git a/doc/shading/distance-attenuation.svg b/doc/shading/distance-attenuation.svg index a50c8df..e4f6543 100644 --- a/doc/shading/distance-attenuation.svg +++ b/doc/shading/distance-attenuation.svg @@ -1,35 +1,91 @@ - - - - - - Light - - - - d = 100 - d = 250 - - - - bright - - - - medium - - - - dim - - - - attenuation = - 1 / (1 + 0.0001·d²) - - - Simplified inverse square law avoids harsh cutoffs + + + + + + + + + +Distance Attenuation +light intensity falls off with distance from source + + + + + + + + + + + + +Light + + + + + + +0.99 + +d = 100 + + + + +0.52 + +d = 300 + + + + +0.29 + +d = 500 + +← attenuation factor shown above each surface → + + +attenuation vs distance + + +d +att + +0 + + +0.5 + + +1.0 + + +100 + + +300 + + +500 + + + + + +0.99 +0.52 +0.29 + + + +attenuation = +1 / (1 + 0.0001 · d²) + + +coefficient 0.0001 was tuned for typical scene scales in Sixth 3D diff --git a/doc/shading/index.org b/doc/shading/index.org index 3f9bab6..3a7c96b 100644 --- a/doc/shading/index.org +++ b/doc/shading/index.org @@ -8,39 +8,7 @@ #+OPTIONS: H:20 num:20 #+OPTIONS: author:nil -#+begin_export html - -#+end_export +#+HTML_HEAD: [[file:../index.org][Back to main documentation]] @@ -53,10 +21,10 @@ #+attr_latex: :width 1000px [[file:Shaded sphere.png]] -*Sixth 3D* implements *flat shading* using the Lambert cosine law. Each -polygon receives a single color based on its orientation relative to -light sources. This is a simple yet effective lighting model that gives -3D objects depth and realism. +*Sixth 3D* implements *flat shading* using the [[https://en.wikipedia.org/wiki/Lambert%27s_cosine_law][Lambert cosine +law]]. Each polygon receives a single color based on its orientation +relative to light sources. This is a simple yet effective lighting +model that gives 3D objects depth and realism. ** The Lighting Model: Lambert Cosine Law :PROPERTIES: @@ -65,16 +33,34 @@ light sources. This is a simple yet effective lighting model that gives #+INCLUDE: "lambert-cosine-law.svg" export html -The *Lambert cosine law* states that the brightness of a surface depends -on the angle between its normal vector and the light direction: - -- Surface facing the light (θ = 0°): maximum brightness (=cos(0°) = 1.0=) -- Surface at 45° angle: moderate brightness (=cos(45°) = 0.71=) -- Surface perpendicular to light (θ = 90°): no direct light (=cos(90°) = 0.0=) - -This is computed as the *dot product* of the unit normal vector (N̂) and -unit light direction vector (L̂). The dot product automatically gives the -cosine of the angle between them. +The *Lambert cosine law* determines how much light a surface receives +based on its orientation. A surface facing directly toward a light source +receives maximum illumination; as it tilts away, the illumination decreases +proportionally until it reaches zero when perpendicular to the light +direction. This fundamental principle creates the visual cues that make 3D +objects appear solid and dimensional rather than flat. + +The engine implements this law through the dot product of two vectors. The +[[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/renderer/raster/lighting/LightingManager.html][LightingManager]] computes a unit vector pointing from the polygon's center +to each [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/renderer/raster/lighting/LightSource.html][LightSource]], then calculates the dot product with the surface +normal. When the dot product equals 1.0, the surface faces the light +directly and receives full brightness. At 0.71 (a 45-degree angle), it +receives about 71% illumination. At zero or below, the surface faces away +from the light and receives no direct contribution from that source. The +implementation in [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/renderer/raster/lighting/LightingManager.html#computeLighting()][LightingManager.computeLighting()]] explicitly checks for +positive dot products before adding light contributions, ensuring that +back-facing surfaces skip unnecessary calculations. + +The surface normal itself is computed by [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/geometry/Plane.html#computeNormal()][Plane.computeNormal()]], which takes +the first three vertices of a polygon and calculates their cross product to +find the perpendicular direction. This normal, along with the polygon's +center point calculated by [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.html][SolidPolygon]], is passed to the lighting manager +during the [[file:../rendering-loop/][transform phase]] of the rendering loop. Computing lighting +during this single-threaded phase ensures thread safety and allows the +result to be cached in the polygon's reusable [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.html#shadedColor][shadedColor]] field, avoiding +memory allocation during the subsequent multi-threaded paint phase. See the +[[file:../index.org::#normal-vector][Normal Vector]] section for more details on how normals are computed and used +throughout the engine. ** Light Sources :PROPERTIES: @@ -274,4 +260,4 @@ would be prohibitively expensive. | [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/renderer/raster/lighting/LightSource.html][LightSource]] | Individual light with position, color, intensity | | [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.html][SolidPolygon]] | Polygon shape with shading support | | [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/composite/base/AbstractCompositeShape.html][AbstractCompositeShape]] | Composite shape with shading propagation | -| [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/gui/ViewPanel.html][ViewPanel]] | Provides access to LightingManager | \ No newline at end of file +| [[https://www3.svjatoslav.eu/projects/sixth-3d/apidocs/eu/svjatoslav/sixth/e3d/gui/ViewPanel.html][ViewPanel]] | Provides access to LightingManager | diff --git a/doc/shading/lambert-cosine-law.svg b/doc/shading/lambert-cosine-law.svg index 39d2a2e..1f4e216 100644 --- a/doc/shading/lambert-cosine-law.svg +++ b/doc/shading/lambert-cosine-law.svg @@ -1,43 +1,92 @@ - - - - - - - - - - - - - - - N̂ - normal - - - - Light - - - - L̂ - - - - θ - - - - brightness = - dot(N̂, L̂) - = cos(θ) - - - - - brightness - ← angle determines intensity + + + + + + + + +Lambert Cosine Law +how surface orientation determines light intensity + + + + + + +N̂ +normal + + + + + + + + +Light + +L̂ + +θ +surface polygon + +brightness = +dot( N̂ , L̂ ) + += cos( θ ) + +θ = 0° + + +1.00 +θ = 45° + + +0.71 +θ = 90° + +0.00 + +θ > 90° +back-face → skip +dot < 0 → no contribution +— angle examples — + + + + + + θ = 0° + + + 100% + + + + + + + + 45° + θ = 45° + + + 71% + + + + + + + + 90° + θ = 90° + + 0% (skip) + + +N̂ surface normal + +L̂ light direction diff --git a/doc/style.css b/doc/style.css new file mode 100644 index 0000000..3403e0e --- /dev/null +++ b/doc/style.css @@ -0,0 +1,35 @@ +.flex-center { + display: flex; + justify-content: center; +} + +.flex-center video { + width: min(90%, 1000px); + height: auto; +} + +.responsive-img { + width: min(100%, 1000px); + height: auto; +} + +/* === SVG diagram theme === */ +svg > rect:first-child { + fill: #061018; +} + +svg text[fill="#666"], +svg text[fill="#999"] { + fill: #aaa !important; +} + +svg line[stroke="#ccc"] { + stroke: #445566 !important; +} + +svg { + background-color: #061018; + border-radius: 8px; + display: block; + margin: 0 auto; +} \ No newline at end of file diff --git a/doc/winding-order.svg b/doc/winding-order.svg index 9340194..d82048e 100644 --- a/doc/winding-order.svg +++ b/doc/winding-order.svg @@ -1,4 +1,4 @@ - + @@ -9,26 +9,27 @@ - + + - + - - CCW - - - - V₁ - V₂ - V₃ - FRONT FACE ✓ + + CCW + + + + V₁ + V₂ + V₃ + FRONT FACE ✓ - + - - CW - - - BACK FACE ✗ - (culled — not drawn) + + CW + + + BACK FACE ✗ + (culled — not drawn)