From: Svjatoslav Agejenko Date: Sun, 1 Jun 2025 12:23:34 +0000 (+0300) Subject: Better JavaDoc X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;p=sixth-3d.git 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 --- 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; /** - * Texture object that is always oriented towards the viewer. + * Base class for textures always facing the viewer. + *

+ * 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. + *

+ * 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 { 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 --- 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; +/** + * A glowing 3D point rendered with a circular gradient texture. + *

+ * 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. + *

+ * 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; 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 --- 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; + /** - * 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. + *

+ * 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. + *

+ * 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. + *

+ * 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 { 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 --- 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; + +/** + * Factory for creating Line objects with consistent appearance settings. + *

+ * 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; 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 --- 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; +/** + * Interpolates between two points along a line for scanline rendering. + *

+ * 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. + *

+ * The comparison logic prioritizes interpolators with greater vertical coverage + * to optimize scanline ordering. + */ 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 --- 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; /** - * polygon with solid color. + * A solid-color triangle renderer with mouse interaction support. + *

+ * 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 + *

+ * The static drawPolygon method is designed for reuse by other polygon types. */ 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 --- 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; +/** + * Interpolator for textured polygon edges with perspective correction. + *

+ * 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. + *

+ * The comparison logic ensures proper scanline ordering based on vertical + * coverage and horizontal span. + */ public class PolygonBorderInterpolator implements Comparable {