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}