001: /*
002: * $RCSfile: ShaderProgram.java,v $
003: *
004: * Copyright 2004-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.5 $
028: * $Date: 2008/02/28 20:17:30 $
029: * $State: Exp $
030: */
031:
032: package javax.media.j3d;
033:
034: /**
035: * The ShaderProgram node component object is the abstract base class
036: * for programmable shader programs. Each concrete instance of a
037: * ShaderProgram is a container for a set of Shader objects. The set
038: * of Shaders contained in the ShaderProgram is a complete program for
039: * the Graphics Pipeline Unit (GPU) of the graphics accelerator. It is
040: * specified using the shader language defined by the
041: * ShaderProgram. The currently defined shader languages are: Cg and
042: * GLSL.
043: *
044: * <p>
045: * NOTE: Applications should <i>not</i> extend this class.
046: *
047: * @see Shader
048: * @see ShaderAppearance#setShaderProgram
049: *
050: * @since Java 3D 1.4
051: */
052:
053: public abstract class ShaderProgram extends NodeComponent {
054:
055: /**
056: * Specifies that this ShaderProgram object allows reading
057: * its shaders.
058: */
059: public static final int ALLOW_SHADERS_READ = CapabilityBits.SHADER_PROGRAM_ALLOW_SHADERS_READ;
060:
061: /**
062: * Specifies that this ShaderProgram object allows reading
063: * its shader or vertex attribute names.
064: */
065: public static final int ALLOW_NAMES_READ = CapabilityBits.SHADER_PROGRAM_ALLOW_NAMES_READ;
066:
067: // Array for setting default read capabilities
068: private static final int[] readCapabilities = { ALLOW_SHADERS_READ,
069: ALLOW_NAMES_READ };
070:
071: /*
072: * Default values (copied from GeometryArray.java):
073: *
074: * vertexAttrNames : null<br>
075: */
076:
077: /**
078: * Package scope constructor so it can't be subclassed by classes
079: * outside the javax.media.j3d package.
080: */
081: ShaderProgram() {
082: // set default read capabilities
083: setDefaultReadCapabilities(readCapabilities);
084: }
085:
086: /**
087: * Sets the vertex attribute names array for this ShaderProgram
088: * object. Each element in the array specifies the shader
089: * attribute name that is bound to the corresponding numbered
090: * vertex attribute within a GeometryArray object that uses this
091: * shader program. Array element 0 specifies the name of
092: * GeometryArray vertex attribute 0, array element 1 specifies the
093: * name of GeometryArray vertex attribute 1, and so forth.
094: * The array of names may be null or empty (0 length), but the
095: * elements of the array must be non-null.
096: *
097: * @param vertexAttrNames array of vertex attribute names for this
098: * shader program. A copy of this array is made.
099: *
100: * @exception RestrictedAccessException if the method is called
101: * when this object is part of live or compiled scene graph.
102: *
103: * @exception NullPointerException if any element in the
104: * vertexAttrNames array is null.
105: */
106: public abstract void setVertexAttrNames(String[] vertexAttrNames);
107:
108: /**
109: * Retrieves the vertex attribute names array from this
110: * ShaderProgram object.
111: *
112: * @exception CapabilityNotSetException if appropriate capability is
113: * not set and this object is part of live or compiled scene graph
114: *
115: * @return a copy of this ShaderProgram's array of vertex attribute names.
116: */
117: public abstract String[] getVertexAttrNames();
118:
119: /**
120: * Sets the shader attribute names array for this ShaderProgram
121: * object. Each element in the array specifies a shader
122: * attribute name that may be set via a ShaderAttribute object.
123: * Only those attributes whose names that appear in the shader
124: * attribute names array can be set for a given shader program.
125: * The array of names may be null or empty (0 length), but the
126: * elements of the array must be non-null.
127: *
128: * <p>
129: * TODO: finish this.
130: *
131: * @param shaderAttrNames array of shader attribute names for this
132: * shader program. A copy of this array is made.
133: *
134: * @exception RestrictedAccessException if the method is called
135: * when this object is part of live or compiled scene graph.
136: *
137: * @exception NullPointerException if any element in the
138: * shaderAttrNames array is null.
139: */
140: public abstract void setShaderAttrNames(String[] shaderAttrNames);
141:
142: /**
143: * Retrieves the shader attribute names array from this
144: * ShaderProgram object.
145: *
146: * @exception CapabilityNotSetException if appropriate capability is
147: * not set and this object is part of live or compiled scene graph
148: *
149: * @return a copy of this ShaderProgram's array of shader attribute names.
150: */
151: public abstract String[] getShaderAttrNames();
152:
153: /**
154: * Copies the specified array of shaders into this shader
155: * program. This method makes a shallow copy of the array. The
156: * array of shaders may be null or empty (0 length), but the
157: * elements of the array must be non-null. The shading
158: * language of each shader in the array must match the
159: * subclass. Subclasses may impose additional restrictions.
160: *
161: * @param shaders array of Shader objects to be copied into this
162: * ShaderProgram
163: *
164: * @exception RestrictedAccessException if the method is called
165: * when this object is part of live or compiled scene graph.
166: *
167: * @exception IllegalArgumentException if the shading language of
168: * any shader in the shaders array doesn't match the type of the
169: * subclass.
170: *
171: * @exception NullPointerException if any element in the
172: * shaders array is null.
173: */
174: public abstract void setShaders(Shader[] shaders);
175:
176: /**
177: * Retrieves the array of shaders from this shader program. A
178: * shallow copy of the array is returned. The return value may
179: * be null.
180: *
181: * @return a copy of this ShaderProgram's array of Shader objects
182: *
183: * @exception CapabilityNotSetException if appropriate capability is
184: * not set and this object is part of live or compiled scene graph
185: */
186: public abstract Shader[] getShaders();
187:
188: // Default shader error listener class
189: private static ShaderErrorListener defaultErrorListener = null;
190:
191: synchronized static ShaderErrorListener getDefaultErrorListener() {
192: if (defaultErrorListener == null) {
193: defaultErrorListener = new DefaultErrorListener();
194: }
195:
196: return defaultErrorListener;
197: }
198:
199: static class DefaultErrorListener implements ShaderErrorListener {
200: public void errorOccurred(ShaderError error) {
201: System.err.println();
202: System.err
203: .println("DefaultShaderErrorListener.errorOccurred:");
204: error.printVerbose();
205: }
206: }
207: }
|