1 /* 2 * $RCSfile: Appearance.java,v $ 3 * 4 * Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. 5 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 6 * 7 * This code is free software; you can redistribute it and/or modify it 8 * under the terms of the GNU General Public License version 2 only, as 9 * published by the Free Software Foundation. Sun designates this 10 * particular file as subject to the "Classpath" exception as provided 11 * by Sun in the LICENSE file that accompanied this code. 12 * 13 * This code is distributed in the hope that it will be useful, but WITHOUT 14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 15 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 16 * version 2 for more details (a copy is included in the LICENSE file that 17 * accompanied this code). 18 * 19 * You should have received a copy of the GNU General Public License version 20 * 2 along with this work; if not, write to the Free Software Foundation, 21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 22 * 23 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, 24 * CA 95054 USA or visit www.sun.com if you need additional information or 25 * have any questions. 26 * 27 * $Revision: 1.9 $ 28 * $Date: 2008/02/28 20:17:19 $ 29 * $State: Exp $ 30 */ 31 32 package javax.media.j3d; 33 34 import java.util.Hashtable; 35 36 /** 37 * The Appearance object defines all rendering state that can be set 38 * as a component object of a Shape3D node. The rendering state 39 * consists of the following:<p> 40 * <ul> 41 * <li>Coloring attributes - defines attributes used in color selection 42 * and shading. These attributes are defined in a ColoringAttributes 43 * object.</li><p> 44 * 45 * <li>Line attributes - defines attributes used to define lines, including 46 * the pattern, width, and whether antialiasing is to be used. These 47 * attributes are defined in a LineAttributes object.</li><p> 48 * 49 * <li>Point attributes - defines attributes used to define points, 50 * including the size and whether antialiasing is to be used. These 51 * attributes are defined in a PointAttributes object.</li><p> 52 * 53 * <li>Polygon attributes - defines the attributes used to define 54 * polygons, including culling, rasterization mode (filled, lines, 55 * or points), constant offset, offset factor, and whether back 56 * back facing normals are flipped. These attributes are defined 57 * in a PolygonAttributes object.</li><p> 58 * 59 * <li>Rendering attributes - defines rendering operations, 60 * including the alpha test function and test value, the raster 61 * operation, whether vertex colors are ignored, whether invisible 62 * objects are rendered, and whether the depth buffer is enabled. 63 * These attributes are defined in a RenderingAttributes 64 * object.</li><p> 65 * 66 * <li>Transparency attributes - defines the attributes that affect 67 * transparency of the object, such as the transparency mode 68 * (blended, screen-door), blending function (used in transparency 69 * and antialiasing operations), and a blend value that defines 70 * the amount of transparency to be applied to this Appearance 71 * component object.</li><p> 72 * 73 * <li>Material - defines the appearance of an object under illumination, 74 * such as the ambient color, diffuse color, specular color, emissive 75 * color, and shininess. These attributes are defined in a Material 76 * object.</li><p> 77 * 78 * <li>Texture - defines the texture image and filtering 79 * parameters used when texture mapping is enabled. These attributes 80 * are defined in a Texture object.</li><p> 81 * 82 * <li>Texture attributes - defines the attributes that apply to 83 * texture mapping, such as the texture mode, texture transform, 84 * blend color, and perspective correction mode. These attributes 85 * are defined in a TextureAttributes object.</li><p> 86 * 87 * <li>Texture coordinate generation - defines the attributes 88 * that apply to texture coordinate generation, such as whether 89 * texture coordinate generation is enabled, coordinate format 90 * (2D or 3D coordinates), coordinate generation mode (object 91 * linear, eye linear, or spherical reflection mapping), and the 92 * R, S, and T coordinate plane equations. These attributes 93 * are defined in a TexCoordGeneration object.</li><p> 94 * 95 * <li>Texture unit state - array that defines texture state for each 96 * of <i>N</i> separate texture units. This allows multiple textures 97 * to be applied to geometry. Each TextureUnitState object contains a 98 * Texture object, TextureAttributes, and TexCoordGeneration object 99 * for one texture unit. If the length of the texture unit state 100 * array is greater than 0, then the array is used for all texture 101 * state; the individual Texture, TextureAttributes, and 102 * TexCoordGeneration objects in this Appearance object are not used 103 * and and must not be set by an application. If the length of the 104 * texture unit state array is 0, the multi-texture is disabled and 105 * the Texture, TextureAttributes, and TexCoordGeneration objects 106 * in the Appearance object are used. If the application sets the 107 * existing Texture, TextureAttributes, and TexCoordGeneration 108 * objects to non-null values, they effectively define the state 109 * for texture unit 0. If the TextureUnitState array is set to a 110 * non-null, non-empty array, the individual TextureUnitState 111 * objects define the state for texture units 0 through <i>n</i> 112 * -1. If both the old and new values are set, an exception is thrown. 113 * 114 * </li> 115 * </ul> 116 * 117 * @see ColoringAttributes 118 * @see LineAttributes 119 * @see PointAttributes 120 * @see PolygonAttributes 121 * @see RenderingAttributes 122 * @see TransparencyAttributes 123 * @see Material 124 * @see Texture 125 * @see TextureAttributes 126 * @see TexCoordGeneration 127 * @see TextureUnitState 128 */ 129 public class Appearance extends NodeComponent { 130 131 /** 132 * Specifies that this Appearance object 133 * allows reading its coloringAttributes component 134 * information. 135 */ 136 public static final int 137 ALLOW_COLORING_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_COLORING_ATTRIBUTES_READ; 138 139 /** 140 * Specifies that this Appearance object 141 * allows writing its coloringAttributes component 142 * information. 143 */ 144 public static final int 145 ALLOW_COLORING_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_COLORING_ATTRIBUTES_WRITE; 146 147 /** 148 * Specifies that this Appearance object 149 * allows reading its transparency component 150 * information. 151 */ 152 public static final int 153 ALLOW_TRANSPARENCY_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_TRANSPARENCY_ATTRIBUTES_READ; 154 155 /** 156 * Specifies that this Appearance object 157 * allows writing its transparency component 158 * information. 159 */ 160 public static final int 161 ALLOW_TRANSPARENCY_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_TRANSPARENCY_ATTRIBUTES_WRITE; 162 163 /** 164 * Specifies that this Appearance object 165 * allows reading its rendering/rasterization component 166 * information. 167 */ 168 public static final int 169 ALLOW_RENDERING_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_RENDERING_ATTRIBUTES_READ; 170 171 /** 172 * Specifies that this Appearance object 173 * allows writing its rendering/rasterization component 174 * information. 175 */ 176 public static final int 177 ALLOW_RENDERING_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_RENDERING_ATTRIBUTES_WRITE; 178 179 /** 180 * Specifies that this Appearance object 181 * allows reading its polygon component 182 * information. 183 */ 184 public static final int 185 ALLOW_POLYGON_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_POLYGON_ATTRIBUTES_READ; 186 187 /** 188 * Specifies that this Appearance object 189 * allows writing its polygon component 190 * information. 191 */ 192 public static final int 193 ALLOW_POLYGON_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_POLYGON_ATTRIBUTES_WRITE; 194 195 /** 196 * Specifies that this Appearance object 197 * allows reading its line component 198 * information. 199 */ 200 public static final int 201 ALLOW_LINE_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_LINE_ATTRIBUTES_READ; 202 203 /** 204 * Specifies that this Appearance object 205 * allows writing its line component 206 * information. 207 */ 208 public static final int 209 ALLOW_LINE_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_LINE_ATTRIBUTES_WRITE; 210 211 /** 212 * Specifies that this Appearance object 213 * allows reading its point component 214 * information. 215 */ 216 public static final int 217 ALLOW_POINT_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_POINT_ATTRIBUTES_READ; 218 219 /** 220 * Specifies that this Appearance object 221 * allows writing its point component 222 * information. 223 */ 224 public static final int 225 ALLOW_POINT_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_POINT_ATTRIBUTES_WRITE; 226 227 /** 228 * Specifies that this Appearance object 229 * allows reading its material component information. 230 */ 231 public static final int 232 ALLOW_MATERIAL_READ = CapabilityBits.APPEARANCE_ALLOW_MATERIAL_READ; 233 234 /** 235 * Specifies that this Appearance object 236 * allows writing its material component information. 237 */ 238 public static final int 239 ALLOW_MATERIAL_WRITE = CapabilityBits.APPEARANCE_ALLOW_MATERIAL_WRITE; 240 241 /** 242 * Specifies that this Appearance object 243 * allows reading its texture component information. 244 */ 245 public static final int 246 ALLOW_TEXTURE_READ = CapabilityBits.APPEARANCE_ALLOW_TEXTURE_READ; 247 248 /** 249 * Specifies that this Appearance object 250 * allows writing its texture component information. 251 */ 252 public static final int 253 ALLOW_TEXTURE_WRITE = CapabilityBits.APPEARANCE_ALLOW_TEXTURE_WRITE; 254 255 /** 256 * Specifies that this Appearance object 257 * allows reading its textureAttributes component 258 * information. 259 */ 260 public static final int 261 ALLOW_TEXTURE_ATTRIBUTES_READ = CapabilityBits.APPEARANCE_ALLOW_TEXTURE_ATTRIBUTES_READ; 262 263 /** 264 * Specifies that this Appearance object 265 * allows writing its textureAttributes component 266 * information. 267 */ 268 public static final int 269 ALLOW_TEXTURE_ATTRIBUTES_WRITE = CapabilityBits.APPEARANCE_ALLOW_TEXTURE_ATTRIBUTES_WRITE; 270 271 /** 272 * Specifies that this Appearance object 273 * allows reading its texture coordinate generation component 274 * information. 275 */ 276 public static final int 277 ALLOW_TEXGEN_READ = CapabilityBits.APPEARANCE_ALLOW_TEXGEN_READ; 278 279 /** 280 * Specifies that this Appearance object 281 * allows writing its texture coordinate generation component 282 * information. 283 */ 284 public static final int 285 ALLOW_TEXGEN_WRITE = CapabilityBits.APPEARANCE_ALLOW_TEXGEN_WRITE; 286 287 /** 288 * Specifies that this Appearance object 289 * allows reading its texture unit state component 290 * information. 291 * 292 * @since Java 3D 1.2 293 */ 294 public static final int ALLOW_TEXTURE_UNIT_STATE_READ = 295 CapabilityBits.APPEARANCE_ALLOW_TEXTURE_UNIT_STATE_READ; 296 297 /** 298 * Specifies that this Appearance object 299 * allows writing its texture unit state component 300 * information. 301 * 302 * @since Java 3D 1.2 303 */ 304 public static final int ALLOW_TEXTURE_UNIT_STATE_WRITE = 305 CapabilityBits.APPEARANCE_ALLOW_TEXTURE_UNIT_STATE_WRITE; 306 307 // Array for setting default read capabilities 308 private static final int[] readCapabilities = { 309 ALLOW_COLORING_ATTRIBUTES_READ, 310 ALLOW_LINE_ATTRIBUTES_READ, 311 ALLOW_MATERIAL_READ, 312 ALLOW_POINT_ATTRIBUTES_READ, 313 ALLOW_POLYGON_ATTRIBUTES_READ, 314 ALLOW_RENDERING_ATTRIBUTES_READ, 315 ALLOW_TEXGEN_READ, 316 ALLOW_TEXTURE_ATTRIBUTES_READ, 317 ALLOW_TEXTURE_READ, 318 ALLOW_TEXTURE_UNIT_STATE_READ, 319 ALLOW_TRANSPARENCY_ATTRIBUTES_READ 320 }; 321 322 /** 323 * Constructs an Appearance component object using defaults for all 324 * state variables. All component object references are initialized 325 * to null. 326 */ Appearance()327 public Appearance() { 328 // Just use default values 329 // set default read capabilities 330 setDefaultReadCapabilities(readCapabilities); 331 } 332 333 /** 334 * Creates the retained mode AppearanceRetained object that this 335 * Appearance component object will point to. 336 */ createRetained()337 void createRetained() { 338 this.retained = new AppearanceRetained(); 339 this.retained.setSource(this); 340 } 341 342 /** 343 * Sets the material object to the specified object. 344 * Setting it to null disables lighting. 345 * @param material object that specifies the desired material 346 * properties 347 * @exception CapabilityNotSetException if appropriate capability is 348 * not set and this object is part of live or compiled scene graph 349 */ setMaterial(Material material)350 public void setMaterial(Material material) { 351 if (isLiveOrCompiled()) 352 if (!this.getCapability(ALLOW_MATERIAL_WRITE)) 353 throw new CapabilityNotSetException(J3dI18N.getString("Appearance0")); 354 ((AppearanceRetained)this.retained).setMaterial(material); 355 } 356 357 /** 358 * Retrieves the current material object. 359 * @return the material object 360 * @exception CapabilityNotSetException if appropriate capability is 361 * not set and this object is part of live or compiled scene graph 362 */ getMaterial()363 public Material getMaterial() { 364 if (isLiveOrCompiled()) 365 if (!this.getCapability(ALLOW_MATERIAL_READ)) 366 throw new CapabilityNotSetException(J3dI18N.getString("Appearance1")); 367 return ((AppearanceRetained)this.retained).getMaterial(); 368 } 369 370 /** 371 * Sets the coloringAttributes object to the specified object. 372 * Setting it to null will result in default attribute usage. 373 * @param coloringAttributes object that specifies the desired 374 * coloringAttributes parameters 375 * @exception CapabilityNotSetException if appropriate capability is 376 * not set and this object is part of live or compiled scene graph 377 */ setColoringAttributes(ColoringAttributes coloringAttributes)378 public void setColoringAttributes(ColoringAttributes coloringAttributes) { 379 if (isLiveOrCompiled()) 380 if (!this.getCapability(ALLOW_COLORING_ATTRIBUTES_WRITE)) 381 throw new CapabilityNotSetException(J3dI18N.getString("Appearance6")); 382 ((AppearanceRetained)this.retained).setColoringAttributes(coloringAttributes); 383 } 384 385 /** 386 * Retrieves the current coloringAttributes object. 387 * @return the coloringAttributes object 388 * @exception CapabilityNotSetException if appropriate capability is 389 * not set and this object is part of live or compiled scene graph 390 */ getColoringAttributes()391 public ColoringAttributes getColoringAttributes() { 392 if (isLiveOrCompiled()) 393 if (!this.getCapability(ALLOW_COLORING_ATTRIBUTES_READ)) 394 throw new CapabilityNotSetException(J3dI18N.getString("Appearance7")); 395 return ((AppearanceRetained)this.retained).getColoringAttributes(); 396 } 397 398 /** 399 * Sets the transparencyAttributes object to the specified object. 400 * Setting it to null will result in default attribute usage. 401 * @param transparencyAttributes object that specifies the desired 402 * transparencyAttributes parameters 403 * @exception CapabilityNotSetException if appropriate capability is 404 * not set and this object is part of live or compiled scene graph 405 */ setTransparencyAttributes(TransparencyAttributes transparencyAttributes)406 public void setTransparencyAttributes(TransparencyAttributes transparencyAttributes) { 407 if (isLiveOrCompiled()) 408 if (!this.getCapability(ALLOW_TRANSPARENCY_ATTRIBUTES_WRITE)) 409 throw new CapabilityNotSetException(J3dI18N.getString("Appearance8")); 410 ((AppearanceRetained)this.retained).setTransparencyAttributes(transparencyAttributes); 411 } 412 413 /** 414 * Retrieves the current transparencyAttributes object. 415 * @return the transparencyAttributes object 416 * @exception CapabilityNotSetException if appropriate capability is 417 * not set and this object is part of live or compiled scene graph 418 */ getTransparencyAttributes()419 public TransparencyAttributes getTransparencyAttributes() { 420 if (isLiveOrCompiled()) 421 if (!this.getCapability(ALLOW_TRANSPARENCY_ATTRIBUTES_READ)) 422 throw new CapabilityNotSetException(J3dI18N.getString("Appearance9")); 423 return ((AppearanceRetained)this.retained).getTransparencyAttributes(); 424 } 425 426 /** 427 * Sets the renderingAttributes object to the specified object. 428 * Setting it to null will result in default attribute usage. 429 * @param renderingAttributes object that specifies the desired 430 * renderingAttributes parameters 431 * @exception CapabilityNotSetException if appropriate capability is 432 * not set and this object is part of live or compiled scene graph 433 */ setRenderingAttributes(RenderingAttributes renderingAttributes)434 public void setRenderingAttributes(RenderingAttributes renderingAttributes) { 435 if (isLiveOrCompiled()) 436 if (!this.getCapability(ALLOW_RENDERING_ATTRIBUTES_WRITE)) 437 throw new CapabilityNotSetException(J3dI18N.getString("Appearance10")); 438 ((AppearanceRetained)this.retained).setRenderingAttributes(renderingAttributes); 439 } 440 441 /** 442 * Retrieves the current renderingAttributes object. 443 * @return the renderingAttributes object 444 * @exception CapabilityNotSetException if appropriate capability is 445 * not set and this object is part of live or compiled scene graph 446 */ getRenderingAttributes()447 public RenderingAttributes getRenderingAttributes() { 448 if (isLiveOrCompiled()) 449 if (!this.getCapability(ALLOW_RENDERING_ATTRIBUTES_READ)) 450 throw new CapabilityNotSetException(J3dI18N.getString("Appearance11")); 451 return ((AppearanceRetained)this.retained).getRenderingAttributes(); 452 } 453 454 /** 455 * Sets the polygonAttributes object to the specified object. 456 * Setting it to null will result in default attribute usage. 457 * @param polygonAttributes object that specifies the desired 458 * polygonAttributes parameters 459 * @exception CapabilityNotSetException if appropriate capability is 460 * not set and this object is part of live or compiled scene graph 461 */ setPolygonAttributes(PolygonAttributes polygonAttributes)462 public void setPolygonAttributes(PolygonAttributes polygonAttributes) { 463 if (isLiveOrCompiled()) 464 if (!this.getCapability(ALLOW_POLYGON_ATTRIBUTES_WRITE)) 465 throw new CapabilityNotSetException(J3dI18N.getString("Appearance12")); 466 ((AppearanceRetained)this.retained).setPolygonAttributes(polygonAttributes); 467 } 468 469 /** 470 * Retrieves the current polygonAttributes object. 471 * @return the polygonAttributes object 472 * @exception CapabilityNotSetException if appropriate capability is 473 * not set and this object is part of live or compiled scene graph 474 */ getPolygonAttributes()475 public PolygonAttributes getPolygonAttributes() { 476 if (isLiveOrCompiled()) 477 if (!this.getCapability(ALLOW_POLYGON_ATTRIBUTES_READ)) 478 throw new CapabilityNotSetException(J3dI18N.getString("Appearance13")); 479 return ((AppearanceRetained)this.retained).getPolygonAttributes(); 480 } 481 482 /** 483 * Sets the lineAttributes object to the specified object. 484 * Setting it to null will result in default attribute usage. 485 * @param lineAttributes object that specifies the desired 486 * lineAttributes parameters 487 * @exception CapabilityNotSetException if appropriate capability is 488 * not set and this object is part of live or compiled scene graph 489 */ setLineAttributes(LineAttributes lineAttributes)490 public void setLineAttributes(LineAttributes lineAttributes) { 491 if (isLiveOrCompiled()) 492 if (!this.getCapability(ALLOW_LINE_ATTRIBUTES_WRITE)) 493 throw new CapabilityNotSetException(J3dI18N.getString("Appearance14")); 494 ((AppearanceRetained)this.retained).setLineAttributes(lineAttributes); 495 } 496 497 /** 498 * Retrieves the current lineAttributes object. 499 * @return the lineAttributes object 500 * @exception CapabilityNotSetException if appropriate capability is 501 * not set and this object is part of live or compiled scene graph 502 */ getLineAttributes()503 public LineAttributes getLineAttributes() { 504 if (isLiveOrCompiled()) 505 if (!this.getCapability(ALLOW_LINE_ATTRIBUTES_READ)) 506 throw new CapabilityNotSetException(J3dI18N.getString("Appearance15")); 507 return ((AppearanceRetained)this.retained).getLineAttributes(); 508 } 509 510 /** 511 * Sets the pointAttributes object to the specified object. 512 * Setting it to null will result in default attribute usage. 513 * @param pointAttributes object that specifies the desired 514 * pointAttributes parameters 515 * @exception CapabilityNotSetException if appropriate capability is 516 * not set and this object is part of live or compiled scene graph 517 */ setPointAttributes(PointAttributes pointAttributes)518 public void setPointAttributes(PointAttributes pointAttributes) { 519 if (isLiveOrCompiled()) 520 if (!this.getCapability(ALLOW_POINT_ATTRIBUTES_WRITE)) 521 throw new CapabilityNotSetException(J3dI18N.getString("Appearance16")); 522 ((AppearanceRetained)this.retained).setPointAttributes(pointAttributes); 523 } 524 525 /** 526 * Retrieves the current pointAttributes object. 527 * @return the pointAttributes object 528 * @exception CapabilityNotSetException if appropriate capability is 529 * not set and this object is part of live or compiled scene graph 530 */ getPointAttributes()531 public PointAttributes getPointAttributes() { 532 if (isLiveOrCompiled()) 533 if (!this.getCapability(ALLOW_POINT_ATTRIBUTES_READ)) 534 throw new CapabilityNotSetException(J3dI18N.getString("Appearance17")); 535 return ((AppearanceRetained)this.retained).getPointAttributes(); 536 } 537 538 /** 539 * Sets the texture object to the specified object. 540 * Setting it to null disables texture mapping. 541 * 542 * <p> 543 * Applications must not set individual texture component objects 544 * (texture, textureAttributes, or texCoordGeneration) and 545 * the texture unit state array in the same Appearance object. 546 * Doing so will result in an exception being thrown. 547 * 548 * @param texture object that specifies the desired texture 549 * map and texture parameters 550 * 551 * @exception CapabilityNotSetException if appropriate capability is 552 * not set and this object is part of live or compiled scene graph 553 * 554 * @exception IllegalStateException if the specified texture 555 * object is non-null and the texture unit state array in this 556 * appearance object is already non-null. 557 * 558 * @exception IllegalSharingException if this Appearance is live and 559 * the specified texture refers to an ImageComponent2D that is being used 560 * by a Canvas3D as an off-screen buffer. 561 * 562 * @exception IllegalSharingException if this Appearance is 563 * being used by an immediate mode context and 564 * the specified texture refers to an ImageComponent2D that is being used 565 * by a Canvas3D as an off-screen buffer. 566 */ setTexture(Texture texture)567 public void setTexture(Texture texture) { 568 if (isLiveOrCompiled()) 569 if (!this.getCapability(ALLOW_TEXTURE_WRITE)) 570 throw new CapabilityNotSetException(J3dI18N.getString("Appearance2")); 571 572 // Do illegal sharing check 573 if(texture != null) { 574 ImageComponent[] images = ((TextureRetained)(texture.retained)).getImages(); 575 if(images != null) { 576 for(int i=0; i<images.length; i++) { 577 validateImageIllegalSharing(images[i]); 578 } 579 } 580 } 581 582 ((AppearanceRetained)this.retained).setTexture(texture); 583 } 584 585 /** 586 * Retrieves the current texture object. 587 * @return the texture object 588 * @exception CapabilityNotSetException if appropriate capability is 589 * not set and this object is part of live or compiled scene graph 590 */ getTexture()591 public Texture getTexture() { 592 if (isLiveOrCompiled()) 593 if (!this.getCapability(ALLOW_TEXTURE_READ)) 594 throw new CapabilityNotSetException(J3dI18N.getString("Appearance3")); 595 return ((AppearanceRetained)this.retained).getTexture(); 596 } 597 598 /** 599 * Sets the textureAttributes object to the specified object. 600 * Setting it to null will result in default attribute usage. 601 * 602 * <p> 603 * Applications must not set individual texture component objects 604 * (texture, textureAttributes, or texCoordGeneration) and 605 * the texture unit state array in the same Appearance object. 606 * Doing so will result in an exception being thrown. 607 * 608 * @param textureAttributes object that specifies the desired 609 * textureAttributes map and textureAttributes parameters 610 * 611 * @exception CapabilityNotSetException if appropriate capability is 612 * not set and this object is part of live or compiled scene graph 613 * 614 * @exception IllegalStateException if the specified textureAttributes 615 * object is non-null and the texture unit state array in this 616 * appearance object is already non-null. 617 */ setTextureAttributes(TextureAttributes textureAttributes)618 public void setTextureAttributes(TextureAttributes textureAttributes) { 619 if (isLiveOrCompiled()) 620 if (!this.getCapability(ALLOW_TEXTURE_ATTRIBUTES_WRITE)) 621 throw new CapabilityNotSetException(J3dI18N.getString("Appearance4")); 622 ((AppearanceRetained)this.retained).setTextureAttributes(textureAttributes); 623 } 624 625 /** 626 * Retrieves the current textureAttributes object. 627 * @return the textureAttributes object 628 * @exception CapabilityNotSetException if appropriate capability is 629 * not set and this object is part of live or compiled scene graph 630 */ getTextureAttributes()631 public TextureAttributes getTextureAttributes() { 632 if (isLiveOrCompiled()) 633 if (!this.getCapability(ALLOW_TEXTURE_ATTRIBUTES_READ)) 634 throw new CapabilityNotSetException(J3dI18N.getString("Appearance5")); 635 return ((AppearanceRetained)this.retained).getTextureAttributes(); 636 } 637 638 /** 639 * Sets the texCoordGeneration object to the specified object. 640 * Setting it to null disables texture coordinate generation. 641 * 642 * <p> 643 * Applications must not set individual texture component objects 644 * (texture, textureAttributes, or texCoordGeneration) and 645 * the texture unit state array in the same Appearance object. 646 * Doing so will result in an exception being thrown. 647 * 648 * @param texCoordGeneration object that specifies the texture coordinate 649 * generation parameters 650 * 651 * @exception CapabilityNotSetException if appropriate capability is 652 * not set and this object is part of live or compiled scene graph 653 * 654 * @exception IllegalStateException if the specified texCoordGeneration 655 * object is non-null and the texture unit state array in this 656 * appearance object is already non-null. 657 */ setTexCoordGeneration(TexCoordGeneration texCoordGeneration)658 public void setTexCoordGeneration(TexCoordGeneration texCoordGeneration) { 659 if (isLiveOrCompiled()) 660 if (!this.getCapability(ALLOW_TEXGEN_WRITE)) 661 throw new CapabilityNotSetException(J3dI18N.getString("Appearance18")); 662 ((AppearanceRetained)this.retained).setTexCoordGeneration(texCoordGeneration); 663 } 664 665 /** 666 * Retrieves the current texCoordGeneration object. 667 * @return the texCoordGeneration object 668 * @exception CapabilityNotSetException if appropriate capability is 669 * not set and this object is part of live or compiled scene graph 670 */ getTexCoordGeneration()671 public TexCoordGeneration getTexCoordGeneration() { 672 if (isLiveOrCompiled()) 673 if (!this.getCapability(ALLOW_TEXGEN_READ)) 674 throw new CapabilityNotSetException(J3dI18N.getString("Appearance19")); 675 return ((AppearanceRetained)this.retained).getTexCoordGeneration(); 676 } 677 678 /** 679 * Sets the texture unit state array for this appearance object to the 680 * specified array. A shallow copy of the array of references to 681 * the TextureUnitState objects is made. If the specified array 682 * is null or if the length of the array is 0, multi-texture is 683 * disabled. Within the array, a null TextureUnitState element 684 * disables the corresponding texture unit. 685 * 686 * <p> 687 * Applications must not set individual texture component objects 688 * (texture, textureAttributes, or texCoordGeneration) and 689 * the texture unit state array in the same Appearance object. 690 * Doing so will result in an exception being thrown. 691 * 692 * @param stateArray array of TextureUnitState objects that 693 * specify the desired texture state for each unit. The length of 694 * this array specifies the maximum number of texture units that 695 * will be used by this appearance object. The texture units are 696 * numbered from <code>0</code> through 697 * <code>stateArray.length-1</code>. 698 * 699 * @exception CapabilityNotSetException if appropriate capability is 700 * not set and this object is part of live or compiled scene graph 701 * 702 * @exception IllegalStateException if the specified array is 703 * non-null and any of the texture object, textureAttributes 704 * object, or texCoordGeneration object in this appearance object 705 * is already non-null. 706 * 707 * @exception IllegalSharingException if this Appearance is live and 708 * any of the specified textures refers to an ImageComponent2D that is 709 * being used by a Canvas3D as an off-screen buffer. 710 * 711 * @exception IllegalSharingException if this Appearance is 712 * being used by an immediate mode context and 713 * any of the specified textures refers to an ImageComponent2D that is 714 * being used by a Canvas3D as an off-screen buffer. 715 * 716 * @since Java 3D 1.2 717 */ setTextureUnitState(TextureUnitState[] stateArray)718 public void setTextureUnitState(TextureUnitState[] stateArray) { 719 if (isLiveOrCompiled()) 720 if (!this.getCapability(ALLOW_TEXTURE_UNIT_STATE_WRITE)) 721 throw new CapabilityNotSetException(J3dI18N.getString("Appearance20")); 722 723 // Do illegal sharing check 724 if (stateArray != null) { 725 for(int j=0; j<stateArray.length; j++) { 726 if(stateArray[j] != null) { 727 TextureRetained texRetained = 728 ((TextureUnitStateRetained)stateArray[j].retained).texture; 729 if(texRetained != null) { 730 ImageComponent[] images = texRetained.getImages(); 731 if(images != null) { 732 for(int i=0; i<images.length; i++) { 733 validateImageIllegalSharing(images[i]); 734 } 735 } 736 } 737 } 738 } 739 } 740 741 ((AppearanceRetained)this.retained).setTextureUnitState(stateArray); 742 } 743 744 /** 745 * Sets the texture unit state object at the specified index 746 * within the texture unit state array to the specified object. 747 * If the specified object is null, the corresponding texture unit 748 * is disabled. The index must be within the range 749 * <code>[0, stateArray.length-1]</code>. 750 * 751 * @param index the array index of the object to be set 752 * 753 * @param state new texture unit state object 754 * 755 * @exception CapabilityNotSetException if appropriate capability is 756 * not set and this object is part of live or compiled scene graph 757 * @exception NullPointerException if the texture unit state array is 758 * null. 759 * @exception ArrayIndexOutOfBoundsException if <code>index >= 760 * stateArray.length</code>. 761 * 762 * @exception IllegalSharingException if this Appearance is live and 763 * the specified texture refers to an ImageComponent2D that is being used 764 * by a Canvas3D as an off-screen buffer. 765 * 766 * @exception IllegalSharingException if this Appearance is 767 * being used by an immediate mode context and 768 * the specified texture refers to an ImageComponent2D that is being used 769 * by a Canvas3D as an off-screen buffer. 770 * 771 * @since Java 3D 1.2 772 */ setTextureUnitState(int index, TextureUnitState state)773 public void setTextureUnitState(int index, TextureUnitState state) { 774 if (isLiveOrCompiled()) 775 if (!this.getCapability(ALLOW_TEXTURE_UNIT_STATE_WRITE)) 776 throw new CapabilityNotSetException(J3dI18N.getString("Appearance20")); 777 778 // Do illegal sharing check 779 if (state != null) { 780 TextureRetained texRetained = 781 ((TextureUnitStateRetained)state.retained).texture; 782 if(texRetained != null) { 783 ImageComponent[] images = texRetained.getImages(); 784 if(images != null) { 785 for(int i=0; i<images.length; i++) { 786 validateImageIllegalSharing(images[i]); 787 } 788 } 789 } 790 } 791 792 ((AppearanceRetained)this.retained).setTextureUnitState(index, state); 793 } 794 795 /** 796 * Retrieves the array of texture unit state objects from this 797 * Appearance object. A shallow copy of the array of references to 798 * the TextureUnitState objects is returned. 799 * 800 * @return the array of texture unit state objects 801 * 802 * @exception CapabilityNotSetException if appropriate capability is 803 * not set and this object is part of live or compiled scene graph 804 * 805 * @since Java 3D 1.2 806 */ getTextureUnitState()807 public TextureUnitState[] getTextureUnitState() { 808 if (isLiveOrCompiled()) 809 if (!this.getCapability(ALLOW_TEXTURE_UNIT_STATE_READ)) 810 throw new CapabilityNotSetException(J3dI18N.getString("Appearance21")); 811 812 return ((AppearanceRetained)this.retained).getTextureUnitState(); 813 } 814 815 /** 816 * Retrieves the texture unit state object at the specified 817 * index within the texture unit state array. The index must be 818 * within the range <code>[0, stateArray.length-1]</code>. 819 * 820 * @param index the array index of the object to be retrieved 821 * 822 * @return the texture unit state object at the specified index 823 * 824 * @exception CapabilityNotSetException if appropriate capability is 825 * not set and this object is part of live or compiled scene graph 826 * 827 * @since Java 3D 1.2 828 */ getTextureUnitState(int index)829 public TextureUnitState getTextureUnitState(int index) { 830 if (isLiveOrCompiled()) 831 if (!this.getCapability(ALLOW_TEXTURE_UNIT_STATE_READ)) 832 throw new CapabilityNotSetException(J3dI18N.getString("Appearance21")); 833 834 return ((AppearanceRetained)this.retained).getTextureUnitState(index); 835 } 836 837 /** 838 * Retrieves the length of the texture unit state array from 839 * this appearance object. The length of this array specifies the 840 * maximum number of texture units that will be used by this 841 * appearance object. If the array is null, a count of 0 is 842 * returned. 843 * 844 * @return the length of the texture unit state array 845 * 846 * @exception CapabilityNotSetException if appropriate capability is 847 * not set and this object is part of live or compiled scene graph 848 * 849 * @since Java 3D 1.2 850 */ getTextureUnitCount()851 public int getTextureUnitCount() { 852 if (isLiveOrCompiled()) 853 if (!this.getCapability(ALLOW_TEXTURE_UNIT_STATE_READ)) 854 throw new CapabilityNotSetException(J3dI18N.getString("Appearance21")); 855 856 return ((AppearanceRetained)this.retained).getTextureUnitCount(); 857 } 858 859 860 /** 861 * @deprecated replaced with cloneNodeComponent(boolean forceDuplicate) 862 */ cloneNodeComponent()863 public NodeComponent cloneNodeComponent() { 864 Appearance a = new Appearance(); 865 a.duplicateNodeComponent(this); 866 return a; 867 } 868 869 /** 870 * NOTE: Applications should <i>not</i> call this method directly. 871 * It should only be called by the cloneNode method. 872 * 873 * @deprecated replaced with duplicateNodeComponent( 874 * NodeComponent originalNodeComponent, boolean forceDuplicate) 875 */ duplicateNodeComponent(NodeComponent originalNodeComponent)876 public void duplicateNodeComponent(NodeComponent originalNodeComponent) { 877 checkDuplicateNodeComponent(originalNodeComponent); 878 } 879 880 /** 881 * Copies all Appearance information from 882 * <code>originalNodeComponent</code> into 883 * the current node. This method is called from the 884 * <code>cloneNode</code> method which is, in turn, called by the 885 * <code>cloneTree</code> method.<P> 886 * 887 * @param originalNodeComponent the original node to duplicate. 888 * @param forceDuplicate when set to <code>true</code>, causes the 889 * <code>duplicateOnCloneTree</code> flag to be ignored. When 890 * <code>false</code>, the value of each node's 891 * <code>duplicateOnCloneTree</code> variable determines whether 892 * NodeComponent data is duplicated or copied. 893 * 894 * @exception RestrictedAccessException if this object is part of a live 895 * or compiled scenegraph. 896 * 897 * @see Node#cloneTree 898 * @see NodeComponent#setDuplicateOnCloneTree 899 */ duplicateAttributes(NodeComponent originalNodeComponent, boolean forceDuplicate)900 void duplicateAttributes(NodeComponent originalNodeComponent, 901 boolean forceDuplicate) { 902 super.duplicateAttributes(originalNodeComponent, forceDuplicate); 903 904 Hashtable hashtable = originalNodeComponent.nodeHashtable; 905 906 AppearanceRetained app = (AppearanceRetained) originalNodeComponent.retained; 907 908 AppearanceRetained rt = (AppearanceRetained) retained; 909 910 rt.setMaterial((Material) getNodeComponent(app.getMaterial(), 911 forceDuplicate, 912 hashtable)); 913 914 rt.setColoringAttributes((ColoringAttributes) getNodeComponent( 915 app.getColoringAttributes(), 916 forceDuplicate, 917 hashtable)); 918 919 920 rt.setTransparencyAttributes((TransparencyAttributes) getNodeComponent( 921 app.getTransparencyAttributes(), 922 forceDuplicate, 923 hashtable)); 924 925 926 rt.setRenderingAttributes((RenderingAttributes) getNodeComponent( 927 app.getRenderingAttributes(), 928 forceDuplicate, 929 hashtable)); 930 931 932 rt.setPolygonAttributes((PolygonAttributes) getNodeComponent( 933 app.getPolygonAttributes(), 934 forceDuplicate, 935 hashtable)); 936 937 938 rt.setLineAttributes((LineAttributes) getNodeComponent( 939 app.getLineAttributes(), 940 forceDuplicate, 941 hashtable)); 942 943 944 rt.setPointAttributes((PointAttributes) getNodeComponent( 945 app.getPointAttributes(), 946 forceDuplicate, 947 hashtable)); 948 949 rt.setTexture((Texture) getNodeComponent(app.getTexture(), 950 forceDuplicate, 951 hashtable)); 952 953 rt.setTextureAttributes((TextureAttributes) getNodeComponent( 954 app.getTextureAttributes(), 955 forceDuplicate, 956 hashtable)); 957 958 rt.setTexCoordGeneration((TexCoordGeneration) getNodeComponent( 959 app.getTexCoordGeneration(), 960 forceDuplicate, 961 hashtable)); 962 963 TextureUnitState state[] = app.getTextureUnitState(); 964 if (state != null) { 965 rt.setTextureUnitState(state); 966 for (int i=0; i < state.length; i++) { 967 rt.setTextureUnitState(i, (TextureUnitState) 968 getNodeComponent(state[i], 969 forceDuplicate, 970 hashtable)); 971 } 972 } 973 974 } 975 976 /** 977 * This function is called from getNodeComponent() to see if any of 978 * the sub-NodeComponents duplicateOnCloneTree flag is true. 979 * If it is the case, current NodeComponent needs to 980 * duplicate also even though current duplicateOnCloneTree flag is false. 981 * This should be overwrite by NodeComponent which contains sub-NodeComponent. 982 */ duplicateChild()983 boolean duplicateChild() { 984 if (getDuplicateOnCloneTree()) 985 return true; 986 987 AppearanceRetained rt = (AppearanceRetained) retained; 988 989 NodeComponent nc; 990 991 nc = rt.getMaterial(); 992 if ((nc != null) && nc.getDuplicateOnCloneTree()) 993 return true; 994 995 nc = rt.getColoringAttributes(); 996 if ((nc != null) && nc.getDuplicateOnCloneTree()) 997 return true; 998 999 nc = rt.getTransparencyAttributes(); 1000 if ((nc != null) && nc.getDuplicateOnCloneTree()) 1001 return true; 1002 1003 nc = rt.getPolygonAttributes(); 1004 if ((nc != null) && nc.getDuplicateOnCloneTree()) 1005 return true; 1006 1007 nc = rt.getLineAttributes(); 1008 if ((nc != null) && nc.getDuplicateOnCloneTree()) 1009 return true; 1010 1011 nc = rt.getPointAttributes(); 1012 if ((nc != null) && nc.getDuplicateOnCloneTree()) 1013 return true; 1014 1015 nc = rt.getTexture(); 1016 if ((nc != null) && nc.duplicateChild()) 1017 return true; 1018 1019 nc = rt.getTextureAttributes(); 1020 if ((nc != null) && nc.getDuplicateOnCloneTree()) 1021 return true; 1022 1023 nc = rt.getTexCoordGeneration(); 1024 if ((nc != null) && nc.getDuplicateOnCloneTree()) 1025 return true; 1026 1027 // XXXX: TextureUnitState 1028 1029 return false; 1030 } 1031 1032 } 1033