001/*
002 * Renderer 4. 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 three doubles which represent the
011   coordinates of a point in 3-dimensional space.
012<p>
013   When a {@code Vertex} object is created in a client program,
014   before the {@code Vertex} object moves down the graphics rendering
015   pipeline, the coordinates in the {@code Vertex} will be in
016   some model's local coordinate system.
017<p>
018   As a {@code Vertex} object moves down the graphics rendering
019   pipeline, the coordinates in the {@code Vertex} will be transformed
020   from one coordinate system to another.
021<p>
022   A {@code Vertex} object is immutable, so after it gets created it
023   cannot be modified (mutated). So a {@code Vertex} object does not
024   really "move" down the graphics pipeline. When a {@code Vertex}
025   object needs to be transformed, we replace it, with a new
026   {@code Vertex} object, instead of mutating it.
027*/
028public final class Vertex
029{
030   public final double x, y, z; // these are "blank finals"
031
032   /**
033      Construct a new {@code Vertex} using the given
034      {@code x}, {@code y}, and {@code z} coordinates.
035
036      @param x  x-coordinate of the new {@code Vertex}
037      @param y  y-coordinate of the new {@code Vertex}
038      @param z  z-coordinate of the new {@code Vertex}
039   */
040   public Vertex(final double x, final double y, final double z)
041   {
042      this.x = x; // fill in the "blank final" variables
043      this.y = y;
044      this.z = z;
045   }
046
047
048   /**
049      For debugging.
050
051      @return {@link String} representation of this {@code Vertex} object
052   */
053   @Override
054   public String toString()
055   {
056      final int precision = 5;  // the default precision for the format string
057      return toString(precision);
058   }
059
060
061   /**
062      For debugging.
063      <p>
064      Allow the precision of the formatted output to be specified.
065
066      @param precision  precision value for the format string
067      @return {@link String} representation of this {@code Vertex} object
068   */
069   public String toString(final int precision)
070   {
071      final int iWidth = 3; // default width of integer part of the format string
072      return toString(precision, iWidth);
073   }
074
075
076   /**
077      For debugging.
078      <p>
079      Allow the precision and width of the formatted output to be specified.
080      By width, we mean the width of the integer part of each number.
081
082      @param precision  precision value for the format string
083      @param iWidth     width of the integer part of the format string
084      @return {@link String} representation of this {@code Vertex} object
085   */
086   public String toString(final int precision, final int iWidth)
087   {
088      // Here is one way to get programmable precision and width.
089      final int p = precision;      // the precision for the following format string
090      final int t = p + iWidth + 2; // the width for the following format string
091      final String format = "(x,y,z) = (% "+t+"."+p+"f  % "+t+"."+p+"f  % "+t+"."+p+"f)";
092      return String.format(format, x, y, z);
093   }
094}