001/*
002 * Renderer 9. The MIT License.
003 * Copyright (c) 2022 rlkraft@pnw.edu
004 * See LICENSE for details.
005*/
006
007package renderer.scene;
008
009/**
010   A {@code Vertex} object has four doubles which represent the
011   homogeneous coordinates of a point in 3-dimensional space.
012   The fourth, homogeneous, coordinate will usually be 1, but in
013   some stages of the graphics rendering pipeline it can be some
014   other (non-zero) number.
015<p>
016   When a {@code Vertex} object is created in a client program,
017   before the {@code Vertex} object moves down the graphics rendering
018   pipeline, the coordinates in the {@code Vertex} will be in
019   some model's local coordinate system.
020<p>
021   As a {@code Vertex} object moves down the graphics rendering
022   pipeline, the coordinates in the {@code Vertex} will be transformed
023   from one coordinate system to another.
024<p>
025   A {@code Vertex} object is immutable, so after it gets created it
026   cannot be modified (mutated). So a {@code Vertex} object does not
027   really "move" down the graphics pipeline. When a {@code Vertex}
028   object needs to be transformed, we replace it, with a new
029   {@code Vertex} object, instead of mutating it.
030*/
031public final class Vertex
032{
033   public final double x, y, z, w; // a vertex in homogenous coordinates
034
035   /**
036      Construct a new {@code Vertex} (with homogeneous coordinates)
037      using the given {@code x}, {@code y}, and {@code z} coordinates.
038
039      @param x  x-coordinate of the new {@code Vertex}
040      @param y  y-coordinate of the new {@code Vertex}
041      @param z  z-coordinate of the new {@code Vertex}
042   */
043   public Vertex(final double x, final double y, final double z)
044   {
045      this(x, y, z, 1.0);
046   }
047
048
049   /**
050      Construct a new {@code Vertex} with the given homogeneous coordinates.
051
052      @param x  x-coordinate of the new {@code Vertex}
053      @param y  y-coordinate of the new {@code Vertex}
054      @param z  z-coordinate of the new {@code Vertex}
055      @param w  w-coordinate of the new {@code Vertex}
056   */
057   public Vertex(final double x, final double y, final double z, final double w)
058   {
059      this.x = x; // fill in the "blank final" variables
060      this.y = y;
061      this.z = z;
062      this.w = w;
063   }
064
065
066   /**
067      For debugging.
068
069      @return {@link String} representation of this {@code Vertex} object
070   */
071   @Override
072   public String toString()
073   {
074      final int precision = 5;  // the default precision for the format string
075      return toString(precision);
076   }
077
078
079   /**
080      For debugging.
081      <p>
082      Allow the precision of the formatted output to be specified.
083
084      @param precision  precision value for the format string
085      @return {@link String} representation of this {@code Vertex} object
086   */
087   public String toString(final int precision)
088   {
089      final int iWidth = 3; // default width of integer part of the format string
090      return toString(precision, iWidth);
091   }
092
093
094   /**
095      For debugging.
096      <p>
097      Allow the precision and width of the formatted output to be specified.
098      By width, we mean the width of the integer part of each number.
099
100      @param precision  precision value for the format string
101      @param iWidth     width of the integer part of the format string
102      @return {@link String} representation of this {@code Vertex} object
103   */
104   public String toString(final int precision, final int iWidth)
105   {
106      // Here is one way to get programmable precision and width.
107      final int p = precision;      // the precision for the following format string
108      final int t = p + iWidth + 2; // the width for the following format string
109      final String format = "(x,y,z,w)=(% "+t+"."+p+"f  % "+t+"."+p+"f  % "+t+"."+p+"f  % "+t+"."+p+"f)";
110      return String.format(format, x, y, z, w);
111   }
112}