1 /* 2 * Project: VizKit 3 * Version: 2.3 4 5 * Date: 20090823 6 * File: VisualStageBox.h 7 * 8 */ 9 10 /*************************************************************************** 11 12 Copyright (c) 2004-2009 Heiko Wichmann (http://www.imagomat.de/vizkit) 13 14 15 This software is provided 'as-is', without any expressed or implied warranty. 16 In no event will the authors be held liable for any damages 17 arising from the use of this software. 18 19 Permission is granted to anyone to use this software for any purpose, 20 including commercial applications, and to alter it and redistribute it 21 freely, subject to the following restrictions: 22 23 1. The origin of this software must not be misrepresented; 24 you must not claim that you wrote the original software. 25 If you use this software in a product, an acknowledgment 26 in the product documentation would be appreciated 27 but is not required. 28 29 2. Altered source versions must be plainly marked as such, 30 and must not be misrepresented as being the original software. 31 32 3. This notice may not be removed or altered from any source distribution. 33 34 ***************************************************************************/ 35 36 #ifndef VisualStageBox_h 37 #define VisualStageBox_h 38 39 40 #include "VisualTypes.h" 41 #include "VisualGraphicTypes.h" 42 #include "VisualStagePosition.h" 43 #include "VisualItemIdentifier.h" 44 45 46 namespace VizKit { 47 48 class VisualItemIdentifier; // Forward declaration (to avoid include of header file). 49 class VisualAsset; // Forward declaration (to avoid include of header file). 50 class VisualCamera; // Forward declaration (to avoid include of header file). 51 52 /** 53 * Position and dimensions of a box on stage. 54 * Used by VisualAsset as a positioning container. It is the bounding box of the visual asset. 55 */ 56 class VisualStageBox { 57 58 public: 59 60 /** 61 * The constructor. 62 * @param anAssetRef Pointer to the asset the stage box belongs to. 63 */ 64 VisualStageBox(VisualAsset* anAssetRef); 65 66 /** 67 * The destructor. 68 */ 69 ~VisualStageBox(); 70 71 /** 72 * Copy constructor. 73 * @param other Reference to another VisualStageBox. 74 */ 75 VisualStageBox(const VisualStageBox& other); 76 77 /** 78 * Assignment operator. 79 * @param other Reference to another VisualStageBox. 80 */ 81 VisualStageBox& operator=(const VisualStageBox& other); 82 83 /** 84 * Sets the pixel width of the image data. 85 * @param pixelWidth The pixel width of the image data. 86 */ 87 void setContentPixelWidth(uint32 pixelWidth); 88 89 /** 90 * Sets the pixel height of the image data. 91 * @param pixelHeight The pixel height of the image data. 92 */ 93 void setContentPixelHeight(uint32 pixelHeight); 94 95 /** 96 * Sets the depth of the stage box (in coord values). 97 * @param aCoordDepth The depth of the stage box. 98 */ 99 void setCoordDepth(double aCoordDepth); 100 101 /** 102 * Sets value of the front position. 103 * @param aFrontPosition The value of the front position. 104 */ 105 void setFrontPosition(double aFrontPosition); 106 107 /** 108 * Returns the value of the front position. 109 * @return The value of the front position. 110 */ 111 double getFrontPosition(void); 112 113 /** 114 * Sets value of the back position. 115 * @param aBackPosition The value of the back position. 116 */ 117 void setBackPosition(double aBackPosition); 118 119 /** 120 * Returns the value of the back position. 121 * @return The value of the back position. 122 */ 123 double getBackPosition(void); 124 125 /** 126 * Sets the stage position of the box. 127 * @param aPosition The position that is supposed to become the current position. 128 */ 129 void setVisualStagePosition(const VisualStagePosition& aPosition); 130 131 /** 132 * Specifies the scaling behaviour. 133 * @param aScalingBehaviour The requested scaling behaviour. 134 */ 135 void setScalingBehaviour(ScalingBehaviour aScalingBehaviour); 136 137 /** 138 * Specifies the magnification/minification of the stage box when drawn. 139 * @param aScaleFactor The factor by which the stage box should be multiplied when rendered (1.0 means no magnification/minification). 140 */ 141 void setScaleFactor(double aScaleFactor); 142 143 /** 144 * Marks the stage box for update of the coord values (e.g. after setting new relative values of vertex chains). 145 * @remarks To enforce immediate update of the coord values, call update(). 146 */ 147 void setDirty(void); 148 149 /** 150 * Updates the coord values (e.g. after canvas reshape). 151 * @remarks It is preferred to just set the dirty flag by calling setDirty(). By calling setDirty() the update is deferred, the coord values are evaluated lazily. 152 */ 153 void update(void); 154 155 /** 156 * Performs the updates of the coord values in case it is needed (because the values have been marked as dirty before). 157 */ 158 void updateIfNeeded(void); 159 160 /** 161 * Returns the scaling attributes. 162 * @return The scaling attributes. 163 */ 164 ScalingBehaviour getScalingBehaviour(void) const; 165 166 /** 167 * Returns the magnification/minification of the stage box when drawn. 168 * @return The factor by which the stage box is multiplied when rendered (1.0 means no magnification/minification). 169 */ 170 double getScaleFactor(void) const; 171 172 /** 173 * Returns the width of the box. 174 * @return The width of the box. 175 */ 176 double getCoordWidth(void); 177 178 /** 179 * Returns the width of the box (without current scaleFactor, only layout constraints taken into account). 180 * @return The width of the box (without current scaleFactor, only layout constraints taken into account). 181 */ 182 double getUnscaledCoordWidth(void); 183 184 /** 185 * Returns the height of the box. 186 * @return The height of the box. 187 */ 188 double getCoordHeight(void); 189 190 /** 191 * Returns the height of the box (without current scaleFactor, only layout constraints taken into account). 192 * @return The height of the box (without current scaleFactor, only layout constraints taken into account). 193 */ 194 double getUnscaledCoordHeight(void); 195 196 /** 197 * Returns the depth of the box. 198 * @return The depth of the box. 199 */ 200 double getCoordDepth(void); 201 202 /** 203 * Returns the depth of the box (without current scaleFactor, only layout constraints taken into account). 204 * @return The depth of the box (without current scaleFactor, only layout constraints taken into account). 205 */ 206 double getUnscaledCoordDepth(void); 207 208 /** 209 * Returns the top coord of the box. 210 * @param vertexChainName The identifier of the vertex chain. If none is specified (default) then the coord position of the bounding box is returned. 211 * @return The top coord of the box. 212 */ 213 double getTopCoord(const VisualItemIdentifier* const vertexChainName = NULL); 214 215 /** 216 * Returns the left coord of the box. 217 * @param vertexChainName The identifier of the vertex chain. If none is specified (default) then the coord position of the bounding box is returned. 218 * @return The left coord of the box. 219 */ 220 double getLeftCoord(const VisualItemIdentifier* const vertexChainName = NULL); 221 222 /** 223 * Returns the bottom coord of the box. 224 * @param vertexChainName The identifier of the vertex chain. If none is specified (default) then the coord position of the bounding box is returned. 225 * @return The bottom coord of the box. 226 */ 227 double getBottomCoord(const VisualItemIdentifier* const vertexChainName = NULL); 228 229 /** 230 * Returns the right coord of the box. 231 * @param vertexChainName The identifier of the vertex chain. If none is specified (default) then the coord position of the bounding box is returned. 232 * @return The right coord of the box. 233 */ 234 double getRightCoord(const VisualItemIdentifier* const vertexChainName = NULL); 235 236 /** 237 * Returns the pixel width of the image data. 238 * @return the pixel width of the image data. 239 */ 240 uint32 getContentPixelWidth(void) const; 241 242 /** 243 * Returns the pixel height of the image data. 244 * @return the pixel height of the image data. 245 */ 246 uint32 getContentPixelHeight(void) const; 247 248 /** 249 * Returns a copy of the stage position of the box. 250 * @return A copy of the stage position of the box. 251 */ 252 VisualStagePosition getVisualStagePosition(void) const; 253 254 /** 255 * Initializes a vertex chain. 256 * @param vertexChainName The identifier of the vertex chain. 257 */ 258 void initializeVertexChain(const VisualItemIdentifier& vertexChainName); 259 260 /** 261 * Adds a vertex to a chain. 262 * @param vertexChainName The identifier of the vertex chain. 263 * @param aVertex The vertex to be added to the vertex chain. 264 */ 265 void addVertexToChain(const VisualItemIdentifier& vertexChainName, VisualVertex* aVertex); 266 267 /** 268 * Returns the vertex chain of the asset identified by that name. 269 * @param vertexChainName The identifier/name (enum) of the vertex chain. 270 * @return The vertex chain identified by that name. 271 */ 272 VertexChain* getVertexChain(const VisualItemIdentifier& vertexChainName); 273 274 /** 275 * Returns the indexed vertex chain. 276 * @param vertexIdx The index of the requested vertex chain. 277 * @return The indexed vertex chain. 278 */ 279 VertexChain* getVertexChain(size_t vertexIdx); 280 281 /** 282 * Returns the identifier of an indexed vertex chain. 283 * @param vertexIdx The index of the requested vertex chain. 284 * @return The identifier of the indexed vertex chain. 285 */ 286 const VisualItemIdentifier& getVertexChainIdentifier(size_t vertexIdx); 287 288 /** 289 * Returns the number of vertex chains of the VisualStageBox. 290 * @return The number of vertex chains of the VisualStageBox. 291 */ 292 size_t getNumberOfVertexChains(void) const; 293 294 /** 295 * Answers the question whether a vertex chain with the identifier exists. 296 * @param vertexChainName The identifier/name (enum) of the vertex chain. 297 * @return True if vertex chain with the identifier exists. 298 */ 299 bool hasVertexChain(const VisualItemIdentifier& vertexChainName) const; 300 301 /** 302 * Clears all vertex chains of the VisualStageBox. 303 */ 304 void removeAllVertexChains(void); 305 306 /** 307 * Clears the vertex chain. 308 * @param vertexChainName The identifier of the VertexChain to remove. 309 */ 310 void removeVertexChain(const VisualItemIdentifier& vertexChainName); 311 312 /** 313 * Returns the minimum relative s-tex coord of all vertex chains of the stage box. 314 * @return The minimum relative s-tex coord of all vertex chains of the stage box. 315 */ 316 double getMinSRelTexCoord(void); 317 318 /** 319 * Returns the minimum relative t-tex coord of all vertex chains of the stage box. 320 * @return The minimum relative t-tex coord of all vertex chains of the stage box. 321 */ 322 double getMinTRelTexCoord(void); 323 324 /** 325 * Returns the maximum relative s-tex coord of all vertex chains of the stage box. 326 * @return The maximum relative s-tex coord of all vertex chains of the stage box. 327 */ 328 double getMaxSRelTexCoord(void); 329 330 /** 331 * Returns the maximum relative t-tex coord of all vertex chains of the stage box. 332 * @return The maximum relative t-tex coord of all vertex chains of the stage box. 333 */ 334 double getMaxTRelTexCoord(void); 335 336 /** 337 * Sets the opacity value (alpha value). 338 * @param anOpacityValue The opacity value (alpha value). 339 */ 340 void setOpacityValue(double anOpacityValue); 341 342 /** 343 * Creates and returns a vertex at the specified position. 344 * @param xPos Position on x-axis (0.0 means: left, 1.0 means: right). 345 * @param yPos Position on y-Axis (0.0 means: bottom, 1.0 means: top). 346 * @param zPos Position on z-Axis (0.0 means: front, 1.0 means: back). 347 * @param aTexCoordSPos An s position of a texture. 348 * @param aTexCoordTPos A t position of a texture. 349 * @param anRGBAColor RGBA color associated with the vertex. 350 * @return A vertex at the specified position. 351 */ 352 VisualVertex* createVertex(double xPos, double yPos, double zPos, double aTexCoordSPos, double aTexCoordTPos, VertexColor anRGBAColor = white); 353 354 /** 355 * Creates and returns a vertex at the specified position. 356 * @param xPos Position on x-axis (0.0 means: left, 1.0 means: right). 357 * @param yPos Position on y-Axis (0.0 means: bottom, 1.0 means: top). 358 * @param zPos Position on z-Axis (0.0 means: front, 1.0 means: back). 359 * @param anRGBAColor RGBA color associated with the vertex. 360 * @return A vertex at the specified position. 361 */ 362 VisualVertex* createVertex(double xPos, double yPos, double zPos, VertexColor anRGBAColor = white); 363 364 /** 365 * Sets the debug mode. 366 * @param requestedDebugMode The debug mode. True turns debug mode on, false turns it off. 367 */ 368 void setDebugMode(bool requestedDebugMode); 369 370 /** 371 * Returns the current debug mode. 372 * @return The current debug mode. True means debug mode is on, false means it is turned off. 373 */ 374 bool getDebugMode(void); 375 376 /** 377 * Calculates the VisualStagePosition according to start position, stop position and current value (between 0.0 and 1.0). 378 * @param startPosition The start position. 379 * @param stopPosition The stop position. 380 * @param currPosition The current value of the animation. 381 * @param currentAssetBox The visual stage box of the current asset which can be queried for additional info. 382 * @return The tweened position. 383 */ 384 static VisualStagePosition tweenVisualStagePosition(const VisualStagePosition& startPosition, const VisualStagePosition& stopPosition, double currPosition, const VisualStageBox& currentAssetBox); 385 386 private: 387 388 /** 389 * Copy method for assignment operator and copy constructor. 390 * @param other Another VisualStageBox. 391 */ 392 void copy(const VisualStageBox& other); 393 394 /** 395 * Calculates the coord dimension of the box according to alignment and margin settings. 396 * @param aCamera The camera with the dimensions of the stage. 397 */ 398 void calcCoords(const VisualCamera& aCamera); 399 400 /** 401 * Applies the scale factor to the coord values. 402 */ 403 void applyScaleFactor(void); 404 405 /** 406 * Updates the position of the existing vertices according to current top, left, bottom, right, front, back coordinates. 407 */ 408 void updateVertices(void); 409 410 bool hasLayout; /**< True if calcCoords() was executed at least once, initial state is false. */ 411 412 double topCoord; /**< The top coord value of the positioned box. */ 413 414 double leftCoord; /**< The left coord value of the positioned box. */ 415 416 double bottomCoord; /**< The bottom coord value of the positioned box. */ 417 418 double rightCoord; /**< The right coord value of the positioned box. */ 419 420 double frontPosition; /**< The value of the front position. */ 421 422 double backPosition; /**< The value of the back position. */ 423 424 double coordWidth; /**< The width of the box measured in coord values. */ 425 426 double unscaledCoordWidth; /**< The width of the box measured in coord values (without scaleFactor). */ 427 428 double coordHeight; /**< The height of the box measured in coord values. */ 429 430 double unscaledCoordHeight; /**< The width of the box measured in coord values (without scaleFactor). */ 431 432 double coordDepth; /**< The depth of the box measured in coord values. */ 433 434 double unscaledCoordDepth; /**< The depth of the box measured in coord values (without scaleFactor). */ 435 436 uint32 contentPixelWidth; /**< The width of the box measured in pixels. */ 437 438 uint32 contentPixelHeight; /**< The height of the box measured in pixels. */ 439 440 VisualStagePosition stagePosition; /**< The dimensionless position of the box. */ 441 442 ScalingBehaviour scalingBehaviour; /**< Specifies the scaling behaviour. */ 443 444 double scaleFactor; /**< The factor by which the stage box should be multiplied when rendered (1.0 means no magnification/minification). */ 445 446 /** A VertexChainMap is a map of vertex chains. */ 447 typedef std::map<VisualItemIdentifier, VertexChain*> VertexChainMap; 448 449 /** The map of the vertex chains. */ 450 VertexChainMap vertexChainMap; 451 452 /** A VertexChainMapIterator is the iterator of a VertexChainMap. */ 453 typedef VertexChainMap::iterator VertexChainMapIterator; 454 455 /** A VertexChainMapIterator is the const iterator of a VertexChainMap. */ 456 typedef VertexChainMap::const_iterator ConstVertexChainMapIterator; 457 458 /** A dummy identifier returned in case a search result was empty. */ 459 VisualItemIdentifier notFoundIdentifier; 460 461 /** Pointer to the asset the stage box belongs to. */ 462 VisualAsset* assetRef; 463 464 /** True if stage box is in debug mode, false otherwise. */ 465 bool debugMode; 466 }; 467 468 } 469 470 #endif /* VisualStageBox_h */ 471