Improved code readability

[sixth-3d.git] / src / main / java / eu / svjatoslav / sixth / e3d / renderer / raster / shapes / basic / ForwardOrientedTexture.java

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 9467e92..7f13783 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
@@ -1,5 +1,5 @@
 /*
- * Sixth 3D engine. Author: Svjatoslav Agejenko. 
+ * Sixth 3D engine. Author: Svjatoslav Agejenko.
  * This project is released under Creative Commons Zero (CC0) license.
  */
 package eu.svjatoslav.sixth.e3d.renderer.raster.shapes.basic;
@@ -13,8 +13,17 @@ import eu.svjatoslav.sixth.e3d.renderer.raster.texture.TextureBitmap;
 
 public class ForwardOrientedTexture extends AbstractCoordinateShape {
 
-    private static final double SIZE_MULTIPLIER = 0.005;
+    private static final double SCALE_MULTIPLIER = 0.005;
     public final Texture texture;
+
+    /**
+     * Scale of the texture object.
+     *
+     * Object rendered visible size on the screen depends on underlying texture size and scale.
+     *
+     * 0 means that object will be infinitely small.
+     * 1 in recommended value to maintain sharpness of the texture as seen by the viewer.
+     */
     private double scale;
 
     public ForwardOrientedTexture(final Point3D point, final double scale,
@@ -24,18 +33,23 @@ public class ForwardOrientedTexture extends AbstractCoordinateShape {
         setScale(scale);
     }
 
+    /**
+     * Paint the texture on the screen (targetRenderingArea)
+     *
+     * @param targetRenderingArea the screen to paint on
+     */
     @Override
     public void paint(final RenderingContext targetRenderingArea) {
 
+        // distance from camera/viewer to center of the texture
         final double z = coordinates[0].transformedCoordinate.z;
 
+        // compute forward oriented texture visible distance from center
         final double visibleHorizontalDistanceFromCenter = (targetRenderingArea.width
-                * scale * texture.primaryBitmap.width)
-                / z;
+                * scale * texture.primaryBitmap.width) / z;
 
         final double visibleVerticalDistanceFromCenter = (targetRenderingArea.width
-                * scale * texture.primaryBitmap.height)
-                / z;
+                * scale * texture.primaryBitmap.height) / z;
 
         // compute visible pixel density, and get appropriate bitmap
         final double zoom = (visibleHorizontalDistanceFromCenter * 2)
@@ -43,61 +57,68 @@ public class ForwardOrientedTexture extends AbstractCoordinateShape {
 
         final TextureBitmap textureBitmap = texture.getZoomedBitmap(zoom);
 
-        final Point2D onScreenLocation = coordinates[0].onScreenCoordinate;
+        final Point2D onScreenCoordinate = coordinates[0].onScreenCoordinate;
 
         // compute Y
-        final int initialYStart = (int) (onScreenLocation.y - visibleVerticalDistanceFromCenter);
-        final int initialYEnd = (int) (onScreenLocation.y + visibleVerticalDistanceFromCenter);
-        final int maxYDistance = initialYEnd - initialYStart;
+        final int onScreenUncappedYStart = (int) (onScreenCoordinate.y - visibleVerticalDistanceFromCenter);
+        final int onScreenUncappedYEnd = (int) (onScreenCoordinate.y + visibleVerticalDistanceFromCenter);
+        final int onScreenUncappedHeight = onScreenUncappedYEnd - onScreenUncappedYStart;
 
-        int yStart = initialYStart;
-        int yEnd = initialYEnd;
+        int onScreenCappedYStart = onScreenUncappedYStart;
+        int onScreenCappedYEnd = onScreenUncappedYEnd;
 
-        if (yStart < 0)
-            yStart = 0;
+        // cap Y to upper screen border
+        if (onScreenCappedYStart < 0)
+            onScreenCappedYStart = 0;
 
-        if (yEnd > targetRenderingArea.height)
-            yEnd = targetRenderingArea.height;
+        // cap Y to lower screen border
+        if (onScreenCappedYEnd > targetRenderingArea.height)
+            onScreenCappedYEnd = targetRenderingArea.height;
 
         // compute X
-        final int initialXStart = (int) (onScreenLocation.x - visibleHorizontalDistanceFromCenter);
-        final int initialXEnd = (int) (onScreenLocation.x + visibleHorizontalDistanceFromCenter);
-        final int maxXDistance = initialXEnd - initialXStart;
-
-        int xStart = initialXStart;
-        int xEnd = initialXEnd;
+        final int onScreenUncappedXStart = (int) (onScreenCoordinate.x - visibleHorizontalDistanceFromCenter);
+        final int onScreenUncappedXEnd = (int) (onScreenCoordinate.x + visibleHorizontalDistanceFromCenter);
+        final int onScreenUncappedWidth = onScreenUncappedXEnd - onScreenUncappedXStart;
 
-        if (xStart < 0)
-            xStart = 0;
+        // cap X to left screen border
+        int onScreenCappedXStart = onScreenUncappedXStart;
+        if (onScreenCappedXStart < 0)
+            onScreenCappedXStart = 0;
 
-        if (xEnd > targetRenderingArea.width)
-            xEnd = targetRenderingArea.width;
+        // cap X to right screen border
+        int onScreenCappedXEnd = onScreenUncappedXEnd;
+        if (onScreenCappedXEnd > targetRenderingArea.width)
+            onScreenCappedXEnd = targetRenderingArea.width;
 
         final byte[] targetRenderingAreaBytes = targetRenderingArea.pixels;
 
         final int textureWidth = textureBitmap.width;
 
-        for (int y = yStart; y < yEnd; y++) {
+        for (int y = onScreenCappedYStart; y < onScreenCappedYEnd; y++) {
 
-            final int relativeTextureOffset = ((textureBitmap.height * (y - initialYStart)) / maxYDistance)
+            final int sourceBitmapScanlinePixel = ((textureBitmap.height * (y - onScreenUncappedYStart)) / onScreenUncappedHeight)
                     * textureWidth;
 
-            int targetRenderingAreaOffset = ((y * targetRenderingArea.width) + xStart) * 4;
+            int targetRenderingAreaOffset = ((y * targetRenderingArea.width) + onScreenCappedXStart) * 4;
 
-            for (int x = xStart; x < xEnd; x++) {
+            for (int x = onScreenCappedXStart; x < onScreenCappedXEnd; x++) {
 
-                final int textureOffset = (relativeTextureOffset + ((textureWidth * (x - initialXStart)) / maxXDistance)) * 4;
+                final int sourceBitmapPixelAddress = (sourceBitmapScanlinePixel + ((textureWidth * (x - onScreenUncappedXStart)) / onScreenUncappedWidth)) * 4;
 
-                textureBitmap.drawPixel(textureOffset,
-                        targetRenderingAreaBytes, targetRenderingAreaOffset);
+                textureBitmap.drawPixel(sourceBitmapPixelAddress, targetRenderingAreaBytes, targetRenderingAreaOffset);
 
                 targetRenderingAreaOffset += 4;
             }
         }
     }
 
+    /**
+     * Set the scale of the texture
+     *
+     * @param scale the scale of the texture
+     */
     public void setScale(final double scale) {
-        this.scale = scale * SIZE_MULTIPLIER;
+        this.scale = scale * SCALE_MULTIPLIER;
     }
 
     public Point3D getLocation() {