001: /*
002: * $RCSfile: TextureCubeMap.java,v $
003: *
004: * Copyright 2001-2008 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
006: *
007: * This code is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU General Public License version 2 only, as
009: * published by the Free Software Foundation. Sun designates this
010: * particular file as subject to the "Classpath" exception as provided
011: * by Sun in the LICENSE file that accompanied this code.
012: *
013: * This code is distributed in the hope that it will be useful, but WITHOUT
014: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: * version 2 for more details (a copy is included in the LICENSE file that
017: * accompanied this code).
018: *
019: * You should have received a copy of the GNU General Public License version
020: * 2 along with this work; if not, write to the Free Software Foundation,
021: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
024: * CA 95054 USA or visit www.sun.com if you need additional information or
025: * have any questions.
026: *
027: * $Revision: 1.7 $
028: * $Date: 2008/02/28 20:17:32 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: import javax.vecmath.*;
035:
036: /**
037: * TextureCubeMap is a subclass of Texture class. It defines
038: * a special kind of texture mapping which is composed of a set of six
039: * 2D images representating the six faces of a cube. The texture coordinate
040: * (s,t,r) is used as a 3D direction vector emanating from the center
041: * of a cube to select a particular face of the cube based on the
042: * largest magnitude coordinate (the major axis). A new 2D texture coordinate
043: * (s,t) is then determined by dividing the other two coordinates (the minor
044: * axes) by the major axis value. The new coordinate is then used for
045: * texel lookup from the selected texture image of this cube map.
046: *
047: * The TextureCubeMap image is defined by specifying the images for each
048: * face of the cube. The cube map texture can be thought of as centered at
049: * the orgin of and aligned to an XYZ coordinate system. The names
050: * of the cube faces are:
051: *
052: * <UL>
053: * <LI>POSITIVE_X</LI>
054: * <LI>NEGATIVE_X</LI>
055: * <LI>POSITIVE_Y</LI>
056: * <LI>NEGATIVE_Y</LI>
057: * <LI>POSITIVE_Z</LI>
058: * <LI>NEGATIVE_Z</LI>
059: * </UL>
060: *
061: * <p>
062: * Note that as of Java 3D 1.5, the texture width and height are no longer
063: * required to be an exact power of two. However, not all graphics devices
064: * supports non-power-of-two textures. If non-power-of-two texture mapping is
065: * unsupported on a particular Canvas3D, textures with a width or height that
066: * are not an exact power of two are ignored for that canvas.
067: *
068: * @see Canvas3D#queryProperties
069: *
070: * @since Java 3D 1.3
071: */
072: public class TextureCubeMap extends Texture {
073:
074: // TODO KCR : NPOT
075:
076: /**
077: * Specifies the face of the cube that is pierced by the positive x axis
078: */
079: public static final int POSITIVE_X = 0;
080:
081: /**
082: * Specifies the face of the cube that is pierced by the negative x axis
083: */
084: public static final int NEGATIVE_X = 1;
085:
086: /**
087: * Specifies the face of the cube that is pierced by the positive y axis
088: */
089: public static final int POSITIVE_Y = 2;
090:
091: /**
092: * Specifies the face of the cube that is pierced by the negative y axis
093: */
094: public static final int NEGATIVE_Y = 3;
095:
096: /**
097: * Specifies the face of the cube that is pierced by the positive z axis
098: */
099: public static final int POSITIVE_Z = 4;
100:
101: /**
102: * Specifies the face of the cube that is pierced by the negative z axis
103: */
104: public static final int NEGATIVE_Z = 5;
105:
106: /**
107: * Constructs a texture object using default values.
108: * Note that the default constructor creates a texture object with
109: * a width of 0 and is, therefore, not useful.
110: */
111: public TextureCubeMap() {
112: super ();
113: }
114:
115: /**
116: * Constructs an empty TextureCubeMap object with specified mipmapMode
117: * format, and width. Image at base level
118: * must be set by
119: * the application using 'setImage' method. If mipmapMode is
120: * set to MULTI_LEVEL_MIPMAP, images for base level through maximum level
121: * must be set.
122: * Note that cube map is square in dimensions, hence specifying width
123: * is sufficient.
124: * Note also that a texture with a non-power-of-two width will
125: * only be rendered on a graphics device that supports non-power-of-two
126: * textures.
127: *
128: * @param mipmapMode type of mipmap for this Texture: One of
129: * BASE_LEVEL, MULTI_LEVEL_MIPMAP.
130: * @param format data format of Textures saved in this object.
131: * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
132: * @param width width (and height) of image at level 0.
133: * @exception IllegalArgumentException if width is not greater
134: * than 0 OR invalid format/mipmapMode is specified.
135: */
136: public TextureCubeMap(int mipmapMode, int format, int width) {
137:
138: super (mipmapMode, format, width, width);
139: }
140:
141: /**
142: * Constructs an empty TextureCubeMap object with specified mipmapMode
143: * format, width, and boundary width. Image at base level
144: * must be set by
145: * the application using 'setImage' method. If mipmapMode is
146: * set to MULTI_LEVEL_MIPMAP, images for base level through maximum level
147: * must be set.
148: * Note that cube map is square in dimensions, hence specifying width
149: * is sufficient.
150: * Note also that a texture with a non-power-of-two width will
151: * only be rendered on a graphics device that supports non-power-of-two
152: * textures.
153: *
154: * @param mipmapMode type of mipmap for this Texture: One of
155: * BASE_LEVEL, MULTI_LEVEL_MIPMAP.
156: * @param format data format of Textures saved in this object.
157: * One of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB, RGBA.
158: * @param width width (and height) of image at level 0. This
159: * does not include the width of the boundary.
160: * @param boundaryWidth width of the boundary, which must be 0 or 1.
161: *
162: * @exception IllegalArgumentException if width is not
163: * greater than 0 OR invalid format/mipmapMode is specified.
164: */
165: public TextureCubeMap(int mipmapMode, int format, int width,
166: int boundaryWidth) {
167:
168: super (mipmapMode, format, width, width, boundaryWidth);
169: }
170:
171: /**
172: * Sets the image for a specified mipmap level of a specified face
173: * of the cube map
174: *
175: * @param level mipmap level
176: * @param face face of the cube map. One of:
177: * <code>POSITIVE_X</code>, <code>NEGATIVE_X</code>,
178: * <code>POSITIVE_Y</code>, <code>NEGATIVE_Y</code>,
179: * <code>POSITIVE_Z</code> or <code>NEGATIVE_Z</code>.
180: * @param image ImageComponent2D object containing the image
181: *
182: * @exception IllegalArgumentException if
183: * <code>face</code> has a value other
184: * than <code>POSITIVE_X</code>, <code>NEGATIVE_X</code>,
185: * <code>POSITIVE_Y</code>, <code>NEGATIVE_Y</code>,
186: * <code>POSITIVE_Z</code> or <code>NEGATIVE_Z</code>.
187: *
188: * @exception CapabilityNotSetException if appropriate capability is
189: * not set and this object is part of live or compiled scene graph
190: *
191: * @exception IllegalSharingException if this TextureCubeMap is live and
192: * the specified image is being used by a Canvas3D as an off-screen buffer.
193: *
194: * @exception IllegalSharingException if this TextureCubeMap is
195: * being used by an immediate mode context and
196: * the specified image is being used by a Canvas3D as an off-screen buffer.
197: */
198: public void setImage(int level, int face, ImageComponent2D image) {
199: if (isLiveOrCompiled()) {
200: if (!this .getCapability(ALLOW_IMAGE_WRITE))
201: throw new CapabilityNotSetException(J3dI18N
202: .getString("TextureCubeMap1"));
203: }
204:
205: validateImageIllegalSharing(image);
206:
207: if (isLive())
208: ((TextureCubeMapRetained) this .retained).setImage(level,
209: face, image);
210: else
211: ((TextureCubeMapRetained) this .retained).initImage(level,
212: face, image);
213: }
214:
215: /**
216: * Sets the array of images for mipmap levels from base level through
217: * max level for a specified face of the cube map
218: *
219: * @param face face of the cube map. One of:
220: * <code>POSITIVE_X</code>, <code>NEGATIVE_X</code>,
221: * <code>POSITIVE_Y</code>, <code>NEGATIVE_Y</code>,
222: * <code>POSITIVE_Z</code> or <code>NEGATIVE_Z</code>.
223: * @param images array of ImageComponent2D objects containing the images
224: *
225: * @exception IllegalArgumentException if
226: * <code>face</code> has a value other
227: * than <code>POSITIVE_X</code>, <code>NEGATIVE_X</code>,
228: * <code>POSITIVE_Y</code>, <code>NEGATIVE_Y</code>,
229: * <code>POSITIVE_Z</code> or <code>NEGATIVE_Z</code>.
230: *
231: * @exception CapabilityNotSetException if appropriate capability is
232: * not set and this object is part of live or compiled scene graph
233: *
234: * @exception IllegalSharingException if this TextureCubeMap is live and
235: * any of the specified images are being used by a Canvas3D as an
236: * off-screen buffer.
237: *
238: * @exception IllegalSharingException if this TextureCubeMap is
239: * being used by an immediate mode context and
240: * any of the specified images are being used by a Canvas3D as an
241: * off-screen buffer.
242: */
243: public void setImages(int face, ImageComponent2D[] images) {
244: if (isLiveOrCompiled()) {
245: if (!this .getCapability(ALLOW_IMAGE_WRITE))
246: throw new CapabilityNotSetException(J3dI18N
247: .getString("TextureCubeMap1"));
248: }
249:
250: // Do illegal sharing check
251: for (int i = 0; i < images.length; i++) {
252: validateImageIllegalSharing(images[i]);
253: }
254:
255: if (isLive())
256: ((TextureCubeMapRetained) this .retained).setImages(face,
257: images);
258: else
259: ((TextureCubeMapRetained) this .retained).initImages(face,
260: images);
261:
262: }
263:
264: /**
265: * Retrieves the image for a specified mipmap level of a particular
266: * face of the cube map.
267: * @param level mipmap level to get.
268: * @param face face of the cube map. One of:
269: * <code>POSITIVE_X</code>, <code>NEGATIVE_X</code>,
270: * <code>POSITIVE_Y</code>, <code>NEGATIVE_Y</code>,
271: * <code>POSITIVE_Z</code> or <code>NEGATIVE_Z</code>.
272: * @return the ImageComponent object containing the texture image at
273: * the specified mipmap level.
274: *
275: * @exception IllegalArgumentException if
276: * <code>face</code> has a value other
277: * than <code>POSITIVE_X</code>, <code>NEGATIVE_X</code>,
278: * <code>POSITIVE_Y</code>, <code>NEGATIVE_Y</code>,
279: * <code>POSITIVE_Z</code> or <code>NEGATIVE_Z</code>.
280: *
281: * @exception CapabilityNotSetException if appropriate capability is
282: * not set and this object is part of live or compiled scene graph
283: */
284: public ImageComponent getImage(int level, int face) {
285: if (isLiveOrCompiled()) {
286: if (!this .getCapability(ALLOW_IMAGE_READ))
287: throw new CapabilityNotSetException(J3dI18N
288: .getString("TextureCubeMap2"));
289: }
290:
291: return ((TextureCubeMapRetained) this .retained).getImage(level,
292: face);
293: }
294:
295: /**
296: * Retrieves the array of images for all mipmap level of a particular
297: * face of the cube map.
298: * @param face face of the cube map. One of:
299: * <code>POSITIVE_X</code>, <code>NEGATIVE_X</code>,
300: * <code>POSITIVE_Y</code>, <code>NEGATIVE_Y</code>,
301: * <code>POSITIVE_Z</code> or <code>NEGATIVE_Z</code>.
302: * @return an array of ImageComponent object for the particular face of
303: * of the cube map.
304: *
305: * @exception IllegalArgumentException if
306: * <code>face</code> has a value other
307: * than <code>POSITIVE_X</code>, <code>NEGATIVE_X</code>,
308: * <code>POSITIVE_Y</code>, <code>NEGATIVE_Y</code>,
309: * <code>POSITIVE_Z</code> or <code>NEGATIVE_Z</code>.
310: *
311: * @exception CapabilityNotSetException if appropriate capability is
312: * not set and this object is part of live or compiled scene graph
313: */
314: public ImageComponent[] getImages(int face) {
315: if (isLiveOrCompiled()) {
316: if (!this .getCapability(ALLOW_IMAGE_READ))
317: throw new CapabilityNotSetException(J3dI18N
318: .getString("TextureCubeMap2"));
319: }
320:
321: return ((TextureCubeMapRetained) this .retained).getImages(face);
322: }
323:
324: /**
325: * This method is not supported for TextureCubeMap.
326: * A face of the cube map has to be specified when setting an image
327: * for a particular level of the cube map.
328: *
329: * @exception UnsupportedOperationException this method is not supported
330: *
331: * @since Java 3D 1.3
332: */
333: public void setImage(int level, ImageComponent image) {
334: throw new UnsupportedOperationException();
335: }
336:
337: /**
338: * This method is not supported for TextureCubeMap.
339: * A face of the cube map has to be specified when setting images
340: * for the cube map.
341: *
342: * @exception UnsupportedOperationException this method is not supported
343: *
344: * @since Java 3D 1.3
345: */
346: public void setImages(ImageComponent[] images) {
347: throw new UnsupportedOperationException();
348: }
349:
350: /**
351: * This method is not supported for TextureCubeMap.
352: * A face of the cube map has to be specified when retrieving an image
353: * for a particular level of the cube map.
354: *
355: * @exception UnsupportedOperationException this method is not supported
356: *
357: * @since Java 3D 1.3
358: */
359: public ImageComponent getImage(int level) {
360: throw new UnsupportedOperationException();
361: }
362:
363: /**
364: * This method is not supported for TextureCubeMap.
365: * A face of the cube map has to be specified when retrieving images
366: * for the cube map.
367: *
368: * @exception UnsupportedOperationException this method is not supported
369: *
370: * @since Java 3D 1.3
371: */
372: public ImageComponent[] getImages() {
373: throw new UnsupportedOperationException();
374: }
375:
376: /**
377: * Creates a retained mode TextureCubeMapRetained object that this
378: * TextureCubeMap component object will point to.
379: */
380: void createRetained() {
381: this .retained = new TextureCubeMapRetained();
382: this .retained.setSource(this );
383: }
384:
385: /**
386: * NOTE: Applications should not call this method directly.
387: * It should only be called by the cloneNode method.
388: *
389: * @deprecated replaced with duplicateNodeComponent(
390: * NodeComponent originalNodeComponent, boolean forceDuplicate)
391: */
392: public void duplicateNodeComponent(
393: NodeComponent originalNodeComponent) {
394: checkDuplicateNodeComponent(originalNodeComponent);
395: }
396: }
|