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 Position} data structure represents a geometric object
011   in a distinct location in three-dimensional camera space as part
012   of a {@link Scene}.
013<p>
014   A {@code Position} object holds references to a {@link Model} object
015   and a {@link Vector} object. The {@link Model} represents the geometric
016   object in the {@link Scene}. The {@link Vector} determines the model's
017   location in the {@link Camera} coordinate system.
018<p>
019   When the renderer renders this {@code Position}'s {@link Model} into
020   a {@link renderer.framebuffer.FrameBuffer}, the first stage of the
021   rendering pipeline, {@link renderer.pipeline.Model2Camera}, adds this
022   {@code Position}'s translation {@link Vector} to every {@link Vertex}
023   in the {@link Model}'s vertex list, which converts the coordinates in
024   each {@link Vertex} from the model's own local coordinate system to
025   the {@link Camera}'s coordinate system (which is "shared" by all
026   the other models in the scene). This vector addition has the effect
027   of "placing" the model in camera space at an appropriate location.
028*/
029public final class Position
030{
031   private Model model;
032   private Vector translation;
033   public final String name;
034   public boolean visible;
035   public boolean debug;
036
037   /**
038      Construct a {@code Position} with the zero translation {@link Vector}
039      and the given {@link Model} object.
040
041      @param model  {@link Model} object to place at this {@code Position}
042      @throws NullPointerException if {@code model} is {@code null}
043   */
044   public Position(final Model model)
045   {
046      this(model,
047           model.name,          // default Position name
048           new Vector(0, 0, 0), // default translation vector
049           true,                // visible
050           false);              // debug
051   }
052
053
054   /**
055      Construct a {@code Position} with the zero translation {@link Vector},
056      the given {@link String} name, and the given {@link Model} object.
057
058      @param model  {@link Model} object to place at this {@code Position}
059      @param name   {@link String} name for this {@code Position}
060      @throws NullPointerException if {@code model} is {@code null}
061      @throws NullPointerException if {@code name} is {@code null}
062   */
063   public Position(final Model model, final String name)
064   {
065      this(model,
066           name,
067           new Vector(0, 0, 0), // default translation vector
068           true,                // visible
069           false);              // debug
070   }
071
072
073   /**
074      Construct a {@code Position} with the given translation {@link Vector},
075      the given {@link String} name, and the given {@link Model} object.
076
077      @param model        {@link Model} object to place at this {@code Position}
078      @param name         {@link String} name for this {@code Position}
079      @param translation  translation {@link Vector} for this {@code Position}
080      @throws NullPointerException if {@code model} is {@code null}
081      @throws NullPointerException if {@code name} is {@code null}
082      @throws NullPointerException if {@code translation} is {@code null}
083   */
084   public Position(final Model model,
085                   final String name,
086                   final Vector translation)
087   {
088      this(model,
089           name,
090           translation,
091           true,   // visible
092           false); // debug
093   }
094
095
096   /**
097      Construct a {@code Position} with the given translation {@link Vector}
098      and the given {@link Model} object.
099
100      @param model        {@link Model} object to place at this {@code Position}
101      @param translation  translation {@link Vector} for this {@code Position}
102      @throws NullPointerException if {@code model} is {@code null}
103      @throws NullPointerException if {@code translation} is {@code null}
104   */
105   public Position(final Model model,
106                   final Vector translation)
107   {
108      this(model,
109           model.name,  // default Position name
110           translation,
111           true,        // visible
112           false);      // debug
113   }
114
115
116   /**
117      Construct a {@code Position} object with all the given data.
118
119      @param model        {@link Model} object to place at this {@code Position}
120      @param name         {@link String} name for this {@code Position}
121      @param translation  translation {@link Vector} for this {@code Position}
122      @param visible      boolean that determines this {@code Position}'s visibility
123      @param debug        boolean that determines if this {@code Position} is logged
124      @throws NullPointerException if {@code model} is {@code null}
125      @throws NullPointerException if {@code translation} is {@code null}
126      @throws NullPointerException if {@code name} is {@code null}
127   */
128   public Position(final Model model,
129                   final String name,
130                   final Vector translation,
131                   final boolean visible,
132                   final boolean debug)
133   {
134      if (null == model)
135         throw new NullPointerException("model must not be null");
136      if (null == name)
137         throw new NullPointerException("name must not be null");
138      if (null == translation)
139         throw new NullPointerException("translation vector must not be null");
140
141      this.model = model;
142      this.translation = translation;
143      this.name = name;
144      this.visible = visible;
145      this.debug = debug;
146   }
147
148
149   /**
150      Get a reference to this {@code Position}'s {@link Model} object.
151
152      @return a reference to this {@code Position}'s {@link Model} object
153   */
154   public Model getModel()
155   {
156      return this.model;
157   }
158
159
160   /**
161      Set this {@code Position}'s {@link Model} object.
162
163      @param model  {@link Model} object to place at this {@code Position}
164      @return a reference to this {@link Position} object to facilitate chaining method calls
165      @throws NullPointerException if {@code model} is {@code null}
166   */
167   public Position setModel(final Model model)
168   {
169      if (null == model)
170         throw new NullPointerException("model must not be null");
171
172      this.model = model;
173      return this;
174   }
175
176
177   /**
178      Get a reference to this {@code Position}'s {@link Vector} object.
179
180      @return a reference to this {@code Position}'s {@link Vector} object
181   */
182   public Vector getTranslation()
183   {
184      return this.translation;
185   }
186
187
188   /**
189      Set this {@code Position}'s translation {@link Vector} object.
190
191      @param x  translation amount in the x-direction
192      @param y  translation amount in the y-direction
193      @param z  translation amount in the z-direction
194      @return a reference to this {@link Position} object to facilitate chaining method calls
195   */
196   public Position translate(final double x,
197                             final double y,
198                             final double z)
199   {
200      this.translation = new Vector(x, y, z);
201      return this;
202   }
203
204
205   /**
206      For debugging.
207
208      @return {@link String} representation of this {@code Position} object
209   */
210   @Override
211   public String toString()
212   {
213      String result = "";
214      result += "Position: " + name + "\n";
215      result += "This Position's visibility is: " + visible + "\n";
216      result += "This Position's translation is\n";
217      result += translation + "\n";
218      result += "This Position's Model is\n";
219      result += (null == model) ? "null\n" : model;
220      return result;
221   }
222}