Better JavaDoc

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/ForwardOrientedTexture.java b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/ForwardOrientedTexture.java
index 9ec004b..5badc6d 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/ForwardOrientedTexture.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/ForwardOrientedTexture.java
@@ -13,7 +13,16 @@ import eu.svjatoslav.sixth.e3d.renderer.raster.texture.Texture;
 import eu.svjatoslav.sixth.e3d.renderer.raster.texture.TextureBitmap;
 
 /**
 import eu.svjatoslav.sixth.e3d.renderer.raster.texture.TextureBitmap;
 
 /**

- * Texture object that is always oriented towards the viewer.
+ * Base class for textures always facing the viewer.
+ * <p>
+ * This class implements the "billboard" rendering technique where the texture
+ * remains oriented towards the camera regardless of 3D position. The visible size
+ * is calculated based on distance from viewer (z-coordinate) and scale factor.
+ * <p>
+ * The texture mapping algorithm:
+ * 1. Calculates screen coverage based on perspective
+ * 2. Clips to viewport boundaries
+ * 3. Maps texture pixels to screen pixels using proportional scaling

  */
 public class ForwardOrientedTexture extends AbstractCoordinateShape {
 
  */
 public class ForwardOrientedTexture extends AbstractCoordinateShape {
 

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/GlowingPoint.java b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/GlowingPoint.java
index 6541aca..b3b9929 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/GlowingPoint.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/GlowingPoint.java
@@ -15,6 +15,16 @@ import java.util.WeakHashMap;
 import static java.lang.Math.pow;
 import static java.lang.Math.sqrt;
 
 import static java.lang.Math.pow;
 import static java.lang.Math.sqrt;
 

+/**
+ * A glowing 3D point rendered with a circular gradient texture.
+ * <p>
+ * This class creates and reuses textures for glowing points of the same color.
+ * The texture is a circle with an alpha gradient from center to edge, ensuring
+ *  a consistent visual appearance regardless of viewing angle.
+ * <p>
+ * The static set of glowing points enables texture sharing and garbage
+ * collection of unused textures via WeakHashMap.
+ */

 public class GlowingPoint extends ForwardOrientedTexture {
 
     private static final int TEXTURE_RESOLUTION_PIXELS = 100;
 public class GlowingPoint extends ForwardOrientedTexture {
 
     private static final int TEXTURE_RESOLUTION_PIXELS = 100;

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/Line.java b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/Line.java
index 0ad06d8..9a71bb0 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/Line.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/Line.java
@@ -11,10 +11,23 @@ import eu.svjatoslav.sixth.e3d.math.Vertex;
 import eu.svjatoslav.sixth.e3d.renderer.raster.Color;
 import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.AbstractCoordinateShape;
 
 import eu.svjatoslav.sixth.e3d.renderer.raster.Color;
 import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.AbstractCoordinateShape;
 

+

 /**
 /**

- * Line in 3D space.
- *
- * Line is represented by two points, width and color and width.
+ * A 3D line segment with perspective-correct width and alpha blending.
+ * <p>
+ * This class represents a line between two 3D points, rendered with a specified
+ * width that adjusts based on perspective (distance from the viewer).
+ * The line is drawn using interpolators to handle edge cases and alpha blending for
+ * transparency effects.
+ * <p>
+ * The rendering algorithm:
+ * 1. For thin lines (below a threshold), draws single-pixel lines with alpha
+ *    adjustment based on perspective.
+ * 2. For thicker lines, creates four interpolators to define the line's
+ *    rectangular area and fills it scanline by scanline.
+ * <p>
+ * Note: The width is scaled by the LINE_WIDTH_MULTIPLIER and adjusted based on
+ * the distance from the viewer (z-coordinate) to maintain a consistent visual size.

  */
 public class Line extends AbstractCoordinateShape {
 
  */
 public class Line extends AbstractCoordinateShape {
 

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/LineAppearance.java b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/LineAppearance.java
index 4cf0007..c27aad6 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/LineAppearance.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/LineAppearance.java
@@ -7,6 +7,14 @@ package eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic.line;
 import eu.svjatoslav.sixth.e3d.geometry.Point3D;
 import eu.svjatoslav.sixth.e3d.renderer.raster.Color;
 
 import eu.svjatoslav.sixth.e3d.geometry.Point3D;
 import eu.svjatoslav.sixth.e3d.renderer.raster.Color;
 

+
+/**
+ * Factory for creating Line objects with consistent appearance settings.
+ * <p>
+ * This class encapsulates common line styling parameters (width and color) to
+ * avoid redundant configuration. It provides multiple constructors for
+ * flexibility and ensures default values are used when not specified.
+ */

 public class LineAppearance {
 
     private final double lineWidth;
 public class LineAppearance {
 
     private final double lineWidth;

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/LineInterpolator.java b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/LineInterpolator.java
index b0428e2..57f8dee 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/LineInterpolator.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/line/LineInterpolator.java
@@ -4,6 +4,16 @@
  */
 package eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic.line;
 
  */
 package eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic.line;
 

+/**
+ * Interpolates between two points along a line for scanline rendering.
+ * <p>
+ * This class calculates screen coordinates and depth values (d) for a given Y
+ * position. It supports perspective-correct interpolation by tracking the
+ * distance between points and using it to compute step increments.
+ * <p>
+ * The comparison logic prioritizes interpolators with greater vertical coverage
+ * to optimize scanline ordering.
+ */

 public class LineInterpolator {
 
     private double x1, y1, d1, x2, y2, d2;
 public class LineInterpolator {
 
     private double x1, y1, d1, x2, y2, d2;

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.java b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.java
index e941408..c05d84a 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.java
@@ -15,7 +15,16 @@ import eu.svjatoslav.sixth.e3d.renderer.raster.shapes.AbstractCoordinateShape;
 import static eu.svjatoslav.sixth.e3d.geometry.Polygon.pointWithinPolygon;
 
 /**
 import static eu.svjatoslav.sixth.e3d.geometry.Polygon.pointWithinPolygon;
 
 /**

- * polygon with solid color.
+ * A solid-color triangle renderer with mouse interaction support.
+ * <p>
+ * This class implements a high-performance triangle rasterizer using scanline
+ * algorithms. It handles:
+ * - Perspective-correct edge interpolation
+ * - Alpha blending with background pixels
+ * - Viewport clipping
+ * - Mouse hover detection via point-in-polygon tests
+ * <p>
+ * The static drawPolygon method is designed for reuse by other polygon types.

  */
 public class SolidPolygon extends AbstractCoordinateShape {
 
  */
 public class SolidPolygon extends AbstractCoordinateShape {
 

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/texturedpolygon/PolygonBorderInterpolator.java b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/texturedpolygon/PolygonBorderInterpolator.java
index f35448d..5b6c198 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/texturedpolygon/PolygonBorderInterpolator.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/renderer/raster/shapes/basic/texturedpolygon/PolygonBorderInterpolator.java
@@ -8,6 +8,17 @@ import eu.svjatoslav.sixth.e3d.geometry.Point2D;
 
 import static java.lang.Math.abs;
 
 
 import static java.lang.Math.abs;
 

+/**
+ * Interpolator for textured polygon edges with perspective correction.
+ * <p>
+ * This class maps screen coordinates to texture coordinates while maintaining
+ * perspective accuracy.
+ * It's used to create texture-mapped scanlines that adjust for depth (z) to
+ * prevent texture distortion.
+ * <p>
+ * The comparison logic ensures proper scanline ordering based on vertical
+ * coverage and horizontal span.
+ */

 public class PolygonBorderInterpolator implements
         Comparable<PolygonBorderInterpolator> {
 
 public class PolygonBorderInterpolator implements
         Comparable<PolygonBorderInterpolator> {