USE
node is still an independent object, with the USE
value matching the DEF
value in the preceding object. ]]>setUSE()
method resets all other fields to their default values and also releases all child nodes.]]>setUSE()
method resets all other fields to their default values and also releases
all child nodes.
* The field definition holds the static field information such as the field access type, the data type and the name of the field.
The implementation of the toString() method of this class shall return the
full IDL declaration of the field as per the specification, not the UTF8 or
XML format. Implementation of .equals()
shall return true if
the two field definitions share the same access type, data type and name. It
shall not include the underlying field's values at that point in time.
* Add a listener for changes in this field. This works for listening to * changes in a readable field. A future extension to the specification, * or a browser-specific extension, may allow for listeners to be added * to writable nodes as well. *
** A listener instance cannot have multiple simultaneous registrations. * If the listener instance is currently registered, this request shall * be silently ignored. *
* * @param listener The listener to add */ void addX3DEventListener(X3DFieldEventListener listener); /** * Remove a listener for changes in the readable field. If the listener is * not currently registered, this request shall be silently ignored. * * @param listener The listener to remove */ void removeX3DEventListener(X3DFieldEventListener listener);* If the index is outside the bounds of the current array of data values, an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ @Override public long get1JavaValue(int index) { if (index < 0) { String errorNotice = "Index value is negative, thus cannot get1JavaValue at index=" + index + "."; validationResult.append(errorNotice).append("\n"); throw new ArrayIndexOutOfBoundsException(errorNotice); } return (long)MFTime[index]; } /** * Assign a new value array, converting seconds from (long) to (double). * @param newValue is replacement value array to assign */ @Override public void setValue(long[] newValue) { ]]>
* The number of items in the pixels array will be
* width * height
. If there are less items than this an
* ArrayIndexOutOfBoundsException will be generated. The integer values
* are represented according to the number of components.
*
* 1 Component Images
* The integer has the intensity value stored in the lowest byte and can be
* obtained:
*
* intensity = (pixel[i] ) &0xFF; **
* 2 Component Images
* The integer has the transparency value stored in the lowest byte and the
* intensity in the next byte:
*
* intensity = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* 3 Component Images
* The three color components are stored in the integer array as follows:
*
* red = (pixel[i] >> 16) &0xFF; * green = (pixel[i] >> 8) &0xFF; * blue = (pixel[i] ) &0xFF; **
* 4 Component Images
* The integer has the value stored in the array as follows:
*
* red = (pixel[i] >> 24) &0xFF; * green = (pixel[i] >> 16) &0xFF; * blue = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* The width and height values must be greater than or equal to zero. The * number of components is between 1 and 4. Any value outside of these * bounds will generate an IllegalArgumentException. * @param destinationPixels The array to copy pixel values into * @throws InvalidFieldValueException Invalid SFImage data found */ @Override public void getPixels(int[] destinationPixels) { if ((SFImage == null) || (SFImage.length < 3)) { String errorNotice = "Null array or illegal data length for SFImage field type"; validationResult.append(errorNotice).append("\n"); throw new InvalidFieldValueException(errorNotice); } int width = getWidth(); int height = getHeight(); int components = getComponents(); // includes error checks destinationPixels = new int[SFImage.length]; if ((width == 0) || (height == 0) || (components == 0)) { destinationPixels = new int[0]; } else if (SFImage.length > 3) { destinationPixels = new int[width * height * components]; // TODO necessary? destinationPixels = Arrays.copyOfRange(SFImage, 3, SFImage.length); // TODO verify } else { String errorNotice = "Illegal value for SFImage field type, getPixels() cannot get pixel array"; validationResult.append(errorNotice).append("\n"); throw new InvalidFieldValueException(errorNotice); } } /** * Fetch the Java representation of the underlying image from these pixels. * This is the same copy that the browser uses to generate texture * information from. * @return The image reference representing the current state */ @Override public java.awt.image.WritableRenderedImage getImage() { return null; // TODO } /** * Set the image value in the given writable field to the new image defined * by a set of pixels. *
* @param image The new image to use as the source */ @Override public void setImage(java.awt.image.RenderedImage image) { // TODO } /** * Copy a region of the argument RenderedImage to replace a portion of the * current SFimage. *
* The sub image set shall not resize the base image representation and * therefore performs an intersection clip of the provided image. The user * provided image shall be of the same format (pixel depth, pixel * representation) as the original image obtained through the getImage() * method. *
* RenderedImages are row order from top to bottom. A * 4x8 RenderImage is indexed as follows: * *
* * X >01234567 * ---------- * 0 |********| * 1 |********| * 2 |********| * 3 |********| * ^ ---------- * Y * ** * SFImages are row order from bottom to top. A * 4x8 RenderImage is indexed as follows: * *
* * X >01234567 * ---------- * 3 |********| * 2 |********| * 1 |********| * 0 |********| * ^ ---------- * Y * ** *
* Note: The parameter srcYOffset is referenced to the RenderedImage object
* (indexed top to bottom).
*
* The parameter destYOffset is referenced to the SFImage object
* (indexed bottom to top).
*
* @param image The new image to use as the source
* @param sourceWidth The width of the argument sub-image region to copy
* @param sourceHeight The height of the argument sub-image region to copy
* @param sourceXOffset The initial x dimension (width) offset into the
* argument sub-image that begins the region to copy
* @param sourceYOffset The initial y dimension (height) offset into the
* argument sub-image that begins the region to copy
* @param destinationXOffset The initial x dimension (width) offset in the SFimage
* object that begins the region to receive the copy
* @param destinationYOffset The initial y dimension (height) offset in the SFimage
* object that begins the region to receive the copy
*/
@Override
public void setSubImage(java.awt.image.RenderedImage image,
int sourceWidth,
int sourceHeight,
int sourceXOffset,
int sourceYOffset,
int destinationXOffset,
int destinationYOffset)
{
// TODO
}
/**
* Set the image value in the given writable field.
*
* Image values are specified using a width, height and the number of
* components. The number of items in the pixels array must be at least
* width * height
. If there are less items than this an
* ArrayIndexOutOfBoundsException will be generated. The integer values
* are represented according to the number of components. If the integer
* contains values in bytes that are not used by the number of components
* for that image, the values are ignored.
*
* 1 Component Images
* The integer has the intensity value stored in the lowest byte and can be
* obtained:
*
* intensity = (pixel[i] ) &0xFF; **
* 2 Component Images
* The integer has the transparency value stored in the lowest byte and the
* intensity in the next byte:
*
* intensity = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* 3 Component Images
* The three color components are stored in the integer array as follows:
*
* red = (pixel[i] >> 16) &0xFF; * green = (pixel[i] >> 8) &0xFF; * blue = (pixel[i] ) &0xFF; **
* 4 Component Images
* The integer has the value stored in the array as follows:
*
* red = (pixel[i] >> 24) &0xFF; * green = (pixel[i] >> 16) &0xFF; * blue = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* The width and height values must be greater than or equal to zero. The * number of components is between 1 and 4. Any value outside of these * bounds will generate an IllegalArgumentException. * * @param width The width of the image in pixels * @param height The height of the image in pixels * @param components The number of color components [1-4] * @param pixels The array of pixel values as specified above. * @exception IllegalArgumentException The number of components or width/ * height are illegal values. * @exception ArrayIndexOutOfBoundsException The number of pixels provided by the * caller is not enough for the width * height. * @throws IllegalArgumentException Invalid parameter(s) provided, no change was made */ @Override public void setValue(int width, int height, int components, int[] pixels) { if ((width < 0) || (height < 0)) { String errorNotice = "Illegal negative value: width=" + width + ", height=" + height + " for SFImage field type"; validationResult.append(errorNotice).append("\n"); throw new IllegalArgumentException(errorNotice); } if ((components < 1) || (components > 4)) { String errorNotice = "Illegal value, must be in range [1..4]: number of components=" + components + " for SFImage field type"; validationResult.append(errorNotice).append("\n"); throw new IllegalArgumentException(errorNotice); } if (((width * height * components) > 0) && (pixels.length < (width * height))) { String errorNotice = "Illegal number of pixels: pixels.length=" + pixels.length + ", (width * height * components) = " + width + " * " + components + " * " + components + ") = " + (width * height * components) + " for SFImage field type"; validationResult.append(errorNotice).append("\n"); throw new IllegalArgumentException(errorNotice); } SFImage = new int[3 + (width * height)]; SFImage[0] = width; SFImage[1] = height; SFImage[2] = components; System.arraycopy(pixels, 0, SFImage, 3, pixels.length); } ]]>
width * height
. If there are less items than this an
* ArrayIndexOutOfBoundsException will be generated. The integer values
* are represented according to the number of components.
*
* 1 Component Images
* The integer has the intensity value stored in the lowest byte and can be
* obtained:
*
* intensity = (pixel[i] ) &0xFF; **
* 2 Component Images
* The integer has the transparency value stored in the lowest byte and the
* intensity in the next byte:
*
* intensity = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* 3 Component Images
* The three color components are stored in the integer array as follows:
*
* red = (pixel[i] >> 16) &0xFF; * green = (pixel[i] >> 8) &0xFF; * blue = (pixel[i] ) &0xFF; **
* 4 Component Images
* The integer has the value stored in the array as follows:
*
* red = (pixel[i] >> 24) &0xFF; * green = (pixel[i] >> 16) &0xFF; * blue = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* The width and height values must be greater than or equal to zero. The * number of components is between 1 and 4. Any value outside of these * bounds will generate an IllegalArgumentException. * @param imageIndex the index of the selected image * @param pixels The array to copy pixel values into */ @Override public void getPixels(int imageIndex, int[] pixels) { // TODO } /** * Fetch the Java representation of the underlying image from these pixels. * This is the same copy that the browser uses to generate texture * information from. * @param imageIndex the index of the selected image * @return The image reference representing the current state */ @Override public WritableRenderedImage getImage(int imageIndex) { return null; // TODO } /** * Set the image value in the given writable field to the new image defined * by a set of pixels. * @param imageIndex the index of the selected image * @param image The new image to use as the source */ @Override public void setImage(int imageIndex, RenderedImage image) { // TODO } /** * Copy a region of the argument RenderedImage to replace a portion of the * current SFimage. *
* The sub image set shall not resize the base image representation and * therefore performs an intersection clip of the provided image. The user * provided image shall be of the same format (pixel depth, pixel * representation) as the original image obtained through the getImage() * method. *
* RenderedImages are row order from top to bottom. A * 4x8 RenderImage is indexed as follows: * *
* * X >01234567 * ---------- * 0 |********| * 1 |********| * 2 |********| * 3 |********| * ^ ---------- * Y * ** * SFImages are row order from bottom to top. A * 4x8 RenderImage is indexed as follows: * *
* * X >01234567 * ---------- * 3 |********| * 2 |********| * 1 |********| * 0 |********| * ^ ---------- * Y * ** *
* Note: The parameter srcYOffset is referenced to the RenderedImage object
* (indexed top to bottom).
*
* The parameter destYOffset is referenced to the SFImage object
* (indexed bottom to top).
*
* @param imageIndex the index of the selected image
* @param image The new image to use as the source
* @param sourceWidth The width of the argument sub-image region to copy
* @param sourceHeight The height of the argument sub-image region to copy
* @param sourceXOffset The initial x dimension (width) offset into the
* argument sub-image that begins the region to copy
* @param sourceYOffset The initial y dimension (height) offset into the
* argument sub-image that begins the region to copy
* @param destinationXOffset The initial x dimension (width) offset in the SFimage
* object that begins the region to receive the copy
* @param destinationYOffset The initial y dimension (height) offset in the SFimage
* object that begins the region to receive the copy
*/
@Override
public void setSubImage(int imageIndex,
RenderedImage image,
int sourceWidth,
int sourceHeight,
int sourceXOffset,
int sourceYOffset,
int destinationXOffset,
int destinationYOffset)
{
// TODO
}
/**
* Replace a single value at the appropriate location in the existing value array.
* Size of the current underlying value array does not change.
* @param imageIndex the index of the selected image
* @param newValue provides new value to apply
*/
@Override
public void set1Value(int imageIndex, int newValue)
{
// TODO
}
@Override
public void set1Value(int imageIndex,
int width,
int height,
int components,
int[] pixels)
{
// TODO
}
/**
* Assign a new value array containing imageIndex, width, height, and components count, followed by array of pixels.
* @param newValue The newValue to set
*/
@Override
public void setValue(int[] newValue)
{
]]>
* The field definition holds static field information such as the field * access type, data type and name of the field. *
*
* The implementation of the toString() method of this class shall return the
* full IDL declaration of the field as per the specification, not the UTF8 or
* XML format. Implementation of .equals()
shall return true if
* the two field definitions share the same access type, data type and name. It
* shall not include the underlying field's values at that point in time.
*
* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public boolean get1Value(int index); /** * Assign an array subset to this field. * @param size indicates size of result to copy (i.e. the number of typed singleton values) from beginning of newValue array. * @param newValue The replacement value array to (potentially) slice and then assign. */ public void setValue(int size, boolean[] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * @param index is position of selected value in current array * @param newValue provides new value to apply */ public void set1Value(int index, boolean newValue) throws ArrayIndexOutOfBoundsException; /** * Places a new value at the end of the existing value array, increasing the field length accordingly. * @param newValue The newValue to append */ public void append(boolean newValue); /** * Insert a new value prior to the index location in the existing value array, increasing the field length accordingly. * @param index The position for the inserted value in the current array * @param newValue The newValue to insert */ public void insertValue(int index, boolean newValue); ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @param valueDestination The array to be filled in with the selected current field value. * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public void get1Value(int index, float[] valueDestination); /** * Assign a new value to this field. * @param numColors The number of 3-tuple RGB colors in the newValue array * @param newValue The newValue to set */ public void setValue(int numColors, float[] newValue); /** * Assign a new value to this field. * @param numColors The number of 3-tuple RGB colors in the newValue array * @param newValue The newValue to set */ public void setValue(int numColors, float[][] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * WARNING: newValue array length must correspond to tuple size for base type ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @param valueDestination The array to be filled in with the selected current field value. * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public void get1Value(int index, float[] valueDestination); /** * Assign a new value to this field. * @param numColors The number of 3-tuple RGB colors in the newValue array * @param newValue The new value to set */ public void setValue(int numColors, float[] newValue); /** * Assign a new value to this field. * @param numColors The number of 3-tuple RGB colors in the newValue array * @param newValue The new value to set */ public void setValue(int numColors, float[][] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * WARNING: newValue array length must correspond to tuple size for base type ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public double get1Value(int index) throws ArrayIndexOutOfBoundsException; /** * Assign an array subset to this field. * @param size indicates size of result to copy (i.e. the number of typed singleton values) from beginning of newValue array. * @param newValue The replacement value array to (potentially) slice and then assign. */ public void setValue(int size, double[] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * @param index is position of selected value in current array * @param newValue provides new value to apply */ public void set1Value(int index, double newValue) throws ArrayIndexOutOfBoundsException; /** * Places a new value at the end of the existing value array, increasing the field length accordingly. * @param newValue The newValue to append */ public void append(double newValue); /** * Insert a new value prior to the index location in the existing value array, increasing the field length accordingly. * @param index The position for the inserted value in the current array * @param newValue The newValue to insert */ public void insertValue(int index, double newValue); ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public float get1Value(int index) throws ArrayIndexOutOfBoundsException; /** * Assign an array subset to this field. * @param size indicates size of result to copy (i.e. the number of typed singleton values) from beginning of newValue array. * @param newValue The replacement value array to (potentially) slice and then assign. */ public void setValue(int size, float[] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * @param index is position of selected value in current array * @param newValue provides new value to apply */ public void set1Value(int index, float newValue) throws ArrayIndexOutOfBoundsException; /** * Places a new value at the end of the existing value array, increasing the field length accordingly. * @param newValue The newValue to append */ public void append(float newValue); /** * Insert a new value prior to the index location in the existing value array, increasing the field length accordingly. * @param index The position for the inserted value in the current array * @param newValue The newValue to insert */ public void insertValue(int index, float newValue); ]]>width * height
. If there are less items than this an
* ArrayIndexOutOfBoundsException will be generated. The integer values
* are represented according to the number of components.
*
* 1 Component Images
* The integer has the intensity value stored in the lowest byte and can be
* obtained:
*
* intensity = (pixel[i] ) &0xFF; **
* 2 Component Images
* The integer has the transparency value stored in the lowest byte and the
* intensity in the next byte:
*
* intensity = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* 3 Component Images
* The three color components are stored in the integer array as follows:
*
* red = (pixel[i] >> 16) &0xFF; * green = (pixel[i] >> 8) &0xFF; * blue = (pixel[i] ) &0xFF; **
* 4 Component Images
* The integer has the value stored in the array as follows:
*
* red = (pixel[i] >> 24) &0xFF; * green = (pixel[i] >> 16) &0xFF; * blue = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* The width and height values must be greater than or equal to zero. The * number of components is between 1 and 4. Any value outside of these * bounds will generate an IllegalArgumentException. * @param pixels The array to copy pixel values into */ public void getPixels(int[] pixels); /** * Fetch the Java representation of the underlying image from these pixels. * This is the same copy that the browser uses to generate texture * information from. * @return The image reference representing the current state */ public java.awt.image.WritableRenderedImage getImage(); /** * Set the image value in the given writable field to the new image defined * by a set of pixels. *
* @param image The new image to use as the source */ public void setImage(java.awt.image.RenderedImage image); /** * Copy a region of the argument RenderedImage to replace a portion of the * current SFimage. *
* The sub image set shall not resize the base image representation and * therefore performs an intersection clip of the provided image. The user * provided image shall be of the same format (pixel depth, pixel * representation) as the original image obtained through the getImage() * method. *
* RenderedImages are row order from top to bottom. A * 4x8 RenderImage is indexed as follows: * *
* * X >01234567 * ---------- * 0 |********| * 1 |********| * 2 |********| * 3 |********| * ^ ---------- * Y * ** * SFImages are row order from bottom to top. A * 4x8 RenderImage is indexed as follows: * *
* * X >01234567 * ---------- * 3 |********| * 2 |********| * 1 |********| * 0 |********| * ^ ---------- * Y * ** *
* Note: The parameter srcYOffset is referenced to the RenderedImage object
* (indexed top to bottom).
*
* The parameter destYOffset is referenced to the SFImage object
* (indexed bottom to top).
*
* @param image The new image to use as the source
* @param sourceWidth The width of the argument sub-image region to copy
* @param sourceHeight The height of the argument sub-image region to copy
* @param sourceXOffset The initial x dimension (width) offset into the
* argument sub-image that begins the region to copy
* @param sourceYOffset The initial y dimension (height) offset into the
* argument sub-image that begins the region to copy
* @param destinationXOffset The initial x dimension (width) offset in the SFimage
* object that begins the region to receive the copy
* @param destinationYOffset The initial y dimension (height) offset in the SFimage
* object that begins the region to receive the copy
*/
public void setSubImage(java.awt.image.RenderedImage image,
int sourceWidth,
int sourceHeight,
int sourceXOffset,
int sourceYOffset,
int destinationXOffset,
int destinationYOffset);
/**
* Set the image value in the given writable field.
*
* Image values are specified using a width, height and the number of
* components. The number of items in the pixels array must be at least
* width * height
. If there are less items than this an
* ArrayIndexOutOfBoundsException will be generated. The integer values
* are represented according to the number of components. If the integer
* contains values in bytes that are not used by the number of components
* for that image, the values are ignored.
*
* 1 Component Images
* The integer has the intensity value stored in the lowest byte and can be
* obtained:
*
* intensity = (pixel[i] ) &0xFF; **
* 2 Component Images
* The integer has the transparency value stored in the lowest byte and the
* intensity in the next byte:
*
* intensity = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* 3 Component Images
* The three color components are stored in the integer array as follows:
*
* red = (pixel[i] >> 16) &0xFF; * green = (pixel[i] >> 8) &0xFF; * blue = (pixel[i] ) &0xFF; **
* 4 Component Images
* The integer has the value stored in the array as follows:
*
* red = (pixel[i] >> 24) &0xFF; * green = (pixel[i] >> 16) &0xFF; * blue = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* The width and height values must be greater than or equal to zero. The * number of components is between 1 and 4. Any value outside of these * bounds will generate an IllegalArgumentException. * * @param width The width of the image in pixels * @param height The height of the image in pixels * @param components The number of color components [1-4] * @param pixels The array of pixel values as specified above. * @exception IllegalArgumentException The number of components or width/ * height are illegal values. * @exception ArrayIndexOutOfBoundsException The number of pixels provided by the * caller is not enough for the width * height. */ public void setValue(int width, int height, int components, int[] pixels); ]]>
width * height
. If there are less items than this an
* ArrayIndexOutOfBoundsException will be generated. The integer values
* are represented according to the number of components.
*
* 1 Component Images
* The integer has the intensity value stored in the lowest byte and can be
* obtained:
*
* intensity = (pixel[i] ) &0xFF; **
* 2 Component Images
* The integer has the transparency value stored in the lowest byte and the
* intensity in the next byte:
*
* intensity = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* 3 Component Images
* The three color components are stored in the integer array as follows:
*
* red = (pixel[i] >> 16) &0xFF; * green = (pixel[i] >> 8) &0xFF; * blue = (pixel[i] ) &0xFF; **
* 4 Component Images
* The integer has the value stored in the array as follows:
*
* red = (pixel[i] >> 24) &0xFF; * green = (pixel[i] >> 16) &0xFF; * blue = (pixel[i] >> 8) &0xFF; * alpha = (pixel[i] ) &0xFF; **
* The width and height values must be greater than or equal to zero. The * number of components is between 1 and 4. Any value outside of these * bounds will generate an IllegalArgumentException. * @param imageIndex the index of the selected image * @param pixels The array to copy pixel values into */ public void getPixels(int imageIndex, int[] pixels); /** * Fetch the Java representation of the underlying image from these pixels. * This is the same copy that the browser uses to generate texture * information from. * @param imageIndex the index of the selected image * @return The image reference representing the current state */ public WritableRenderedImage getImage(int imageIndex); /** * Set the image value in the given writable field to the new image defined * by a set of pixels. * @param imageIndex the index of the selected image * @param image The new image to use as the source */ public void setImage(int imageIndex, RenderedImage image); /** * Copy a region of the argument RenderedImage to replace a portion of the * current SFimage. *
* The sub image set shall not resize the base image representation and * therefore performs an intersection clip of the provided image. The user * provided image shall be of the same format (pixel depth, pixel * representation) as the original image obtained through the getImage() * method. *
* RenderedImages are row order from top to bottom. A * 4x8 RenderImage is indexed as follows: * *
* * X >01234567 * ---------- * 0 |********| * 1 |********| * 2 |********| * 3 |********| * ^ ---------- * Y * ** * SFImages are row order from bottom to top. A * 4x8 RenderImage is indexed as follows: * *
* * X >01234567 * ---------- * 3 |********| * 2 |********| * 1 |********| * 0 |********| * ^ ---------- * Y * ** *
* Note: The parameter srcYOffset is referenced to the RenderedImage object
* (indexed top to bottom).
*
* The parameter destYOffset is referenced to the SFImage object
* (indexed bottom to top).
*
* @param imageIndex the index of the selected image
* @param image The new image to use as the source
* @param sourceWidth The width of the argument sub-image region to copy
* @param sourceHeight The height of the argument sub-image region to copy
* @param sourceXOffset The initial x dimension (width) offset into the
* argument sub-image that begins the region to copy
* @param sourceYOffset The initial y dimension (height) offset into the
* argument sub-image that begins the region to copy
* @param destinationXOffset The initial x dimension (width) offset in the SFimage
* object that begins the region to receive the copy
* @param destinationYOffset The initial y dimension (height) offset in the SFimage
* object that begins the region to receive the copy
*/
public void setSubImage(int imageIndex,
RenderedImage image,
int sourceWidth,
int sourceHeight,
int sourceXOffset,
int sourceYOffset,
int destinationXOffset,
int destinationYOffset);
/**
* Replace a single value at the appropriate location in the existing value array.
* Size of the current underlying value array does not change.
* @param imageIndex the index of the selected image
* @param newValue provides new value to apply
*/
public void set1Value(int imageIndex, int newValue);
public void set1Value(int imageIndex,
int width,
int height,
int components,
int[] pixels);
/**
* Assign a new value array containing imageIndex, width, height, and components count, followed by array of pixels.
* @param newValue The newValue to set
*/
public void setValue(int[] newValue);
public void setImage(RenderedImage[] image);
/**
* Places a new value at the end of the existing value array, increasing the field length accordingly.
* @param newValue The newValue to append
*/
public void append(RenderedImage[] newValue);
/**
* Insert a new value prior to the index location in the existing value array, increasing the field length accordingly.
* @param index The position for the inserted value in the current array
* @param newValue The newValue to insert
*/
public void insertValue(int index, RenderedImage newValue);
]]>
* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public int get1Value(int index) throws ArrayIndexOutOfBoundsException; /** * Assign an array subset to this field. * @param size indicates size of result to copy (i.e. the number of typed singleton values) from beginning of newValue array. * @param newValue The replacement value array to (potentially) slice and then assign. */ public void setValue(int size, int[] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * @param imageIndex the index of the selected image * @param newValue provides new value to apply */ public void set1Value(int imageIndex, int newValue) throws ArrayIndexOutOfBoundsException; /** * Places a new value at the end of the existing value array, increasing the field length accordingly. * @param newValue The newValue to append */ public void append(int newValue); /** * Insert a new value prior to the index location in the existing value array, increasing the field length accordingly. * @param index The position for the inserted value in the current array * @param newValue The newValue to insert */ public void insertValue(int index, int newValue); ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public X3DNode get1Value(int index); /** * Assign an array subset to this field. * @param size indicates size of result to copy (i.e. the number of typed singleton values) from beginning of newValue array. * @param newValue The replacement value array to (potentially) slice and then assign. */ public void setValue(int size, X3DNode[] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * @param imageIndex the index of the selected image * @param newValue provides new value to apply */ public void set1Value(int imageIndex, X3DNode newValue); /** * Places a new value at the end of the existing value array, increasing the field length accordingly. * @param newValue The newValue to append */ public void append(X3DNode newValue); /** * Insert a new value prior to the imageIndex location in the existing value array, increasing the field length accordingly. * @param imageIndex the index of the selected image * @param newValue The newValue to insert */ public void insertValue(int imageIndex, X3DNode newValue); ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @param valueDestination The array to be filled in with the selected current field value. * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public void get1Value(int index, float[] valueDestination); /** * Assign a new value to this field. * @param numRotations The number of 4-tuple rotations in the newValue array * @param newValue The newValue array of 4-tuple rotations to set */ public void setValue(int numRotations, float[] newValue); /** * Assign a new value to this field. * @param numRotations The number of 4-tuple rotations in the newValue array * @param newValue The newValue square array of 4-tuple rotations to set */ public void setValue(int numRotations, float[][] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * WARNING: newValue array length must correspond to tuple size for base type ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public String get1Value(int index); /** * Assign a new value to this field. * @param numStrings The number of strings in the newValue array * @param newValue The newValue array of strings to set */ public void setValue(int numStrings, String[] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * @param index is position of selected value in current array * @param newValue provides new value to apply */ public void set1Value(int index, String newValue); /** * Places a new value at the end of the existing value array, increasing the field length accordingly. * @param newValue The newValue to append */ public void append(String newValue); /** * Insert a new value prior to the index location in the existing value array, increasing the field length accordingly. * @param index The position for the inserted value in the current array * @param newValue The newValue to insert */ public void insertValue(int index, String newValue); ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public double get1Value(int index); /** ** Get an individual value from the existing field array. *
* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @return The selected value * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public long get1JavaValue(int index); /** * Assign an array subset to this field. * @param size indicates size of result to copy (i.e. the number of typed singleton values) from beginning of newValue array * @param newValue The replacement value array to (potentially) slice and then assign. */ public void setValue(int size, double[] newValue); /** * Assign an array subset to this field. * @param size indicates size of result to copy (i.e. the number of typed singleton values) from beginning of newValue array. * @param newValue The replacement value array to (potentially) slice and then assign. */ public void setValue(int size, long[] newValue); /** * Assign a new value to this field. * @param newValue is replacement value array to assign */ public void setValue(long[] newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * @param index is position of selected value in current array * @param newValue provides new value to apply */ public void set1Value(int index, double newValue); /** * Replace a single value at the appropriate location in the existing value array. * Size of the current underlying value array does not change. * @param index is position of selected value in current array * @param newValue provides new value to apply */ public void set1Value(int index, long newValue); /** * Places a new value at the end of the existing value array, increasing the field length accordingly. * @param newValue The newValue to append */ public void append(double newValue); /** * Places a new value at the end of the existing value array, increasing the field length accordingly. * @param newValue The newValue to append */ public void append(long newValue); /** * Insert a new value prior to the index location in the existing value array, increasing the field length accordingly. * @param index The position for the inserted value in the current array * @param newValue The newValue to insert */ public void insertValue(int index, long newValue); /** * Insert a new value prior to the index location in the existing value array, increasing the field length accordingly. * @param index The position for the inserted value in the current array * @param newValue The newValue to insert */ public void insertValue(int index, double newValue); ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @param valueDestination The array to be filled in with the selected current field value. * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public void get1Value(int index, double[] valueDestination); /** * Assign an array subset to this field. * WARNING: newValue array length must correspond to tuple size for base type ]]>* If the index is outside the bounds of the current array of data values, * an ArrayIndexOutOfBoundsException is thrown. *
* @param index is position of selected value in current array * @param valueDestination The array to be filled in with the selected current field value. * @throws ArrayIndexOutOfBoundsException The index was outside of the bounds of the current array. */ public void get1Value(int index, float[] valueDestination); /** * Assign an array subset to this field. * WARNING: newValue array length must correspond to tuple size for base type ]]>An implementation-independent representation of the class used to access and create browsers. The model follows that used by java.net.Socket. A setImpl method is provided for browser writers to provide the internal implementations of the browser.
An alternative way of doing this is through properties. The class, when it loads first looks for a System property with the key:
x3d.sai.factory.class
If a non-null value is found for this key, it is used as the name of
the class to load as the default browser implementation. If no matching
System property is found, the initializer looks for the file
x3d.properties
in the class path.
(For more information on how this works read
java.lang.ClassLoader.getSystemResourceAsStream()
). If found,
and the file contains a non-null value for the x3d.sai.factory.class
key, this value is used as the name of the class to load as the default browser
implementation.
In either case (System properties or x3d.properties file), this name must
represent the full package qualified name of the class.
If a System property with the required key does not exist, or an x3d.properties
file does not exist or the x3d.properties file does not contain a property with
the required key for the name of the factory class, then
the default class name org.web3d.x3d.sai.DefaultBrowserImpl
is assigned.
The class is loaded when a call is made to getBrowser()
or
createX3DComponent()
using the following method:
Class factory_class = Class.forName(factory_class_name); factory = (BrowserFactoryImpl)factory_class.newInstance();
If a class cast exception is raised at the end, then an error is printed but nothing is done about it. The result would be NullPointerExceptions later in the code. Also, this may cause some security errors in some web browsers.
To provide a custom implementation of the factory (which all
implementations must do) the user has the choice of the above options
of either setting a System property, making sure that an x3d.properties
file appears in the classpath setBrowserFactoryImpl
has not been called at the time that
any of the other methods have been, then the class will attempt to load
the implementation defined in the properties file. Attempting to call the
set implementation method after this point shall result in a X3DException
being generated. Otherwise, it shall use the set implementation.
* If the frame name is a zero length string or null then it is assumed to be * located on the same HTML page as the applet. The index is the number of * the embed X3D player starting from the top of the page. If there are * other non-X3D plugins embedded in the page these are not taken into * account in calculating the embed index. * * @param applet - The applet reference to use * @param frameName - The name of the frame to look into for the browser * @param index - The embed index of the X3D player in the page * @return A reference to the Browser implementation * @exception NotSupportedException The implementation does not support this * type of X3D player. * @exception NoSuchBrowserException Could not locate an X3D player on the * same page as the applet. * @exception ConnectionException An error occurred during the connecting * process */ public static ExternalBrowser getBrowser(Applet applet, String frameName, int index) throws NotSupportedException, NoSuchBrowserException, ConnectionException { if(factory == null) loadFactoryImpl(); // return factory.getBrowser(applet, frameName, index); // TODO fix incorrect method signature return null; } /** * Get a reference to a browser that is located on a remote machine. This * a server application to send scene updates to a number of client browsers * located on remote machines. If there are a number of browsers running on * a remote machine, they can be differentiated by the port number they are * listening on. *
* There is no default port number for X3D players. * * @param address - The address of the machine to connect to * @param port - The port number on that machine to connect to. * @return A reference to the Browser implementation * @exception NotSupportedException The implementation does not support this * type of X3D player. * @exception NoSuchBrowserException Could not locate an X3D player on the * same page as the applet. * @exception UnknownHostException Could not find the machine named in the * address. * @exception ConnectionException An error occurred during the connecting * process */ public static ExternalBrowser getBrowser(InetAddress address, int port) throws NotSupportedException, NoSuchBrowserException, UnknownHostException, ConnectionException { if(factory == null) loadFactoryImpl(); // return factory.getBrowser(address, port); // TODO fix incorrect method signature return null; } /** * Private method to load the resource file and use the appropriate class * defined in the properties file for dealing with the resource management *
* Assumes that the factory reference is currently null as it automatically * writes over the top of it. */ private static void loadFactoryImpl( ) { try { // load the factory class String factory_class_name = vrml_properties.getProperty( FACTORY_CLASS, DEFAULT_FACTORY_CLASS ); Class> factory_class = Class.forName( factory_class_name ); factory = (BrowserFactoryImpl)factory_class.newInstance( ); } catch( ClassNotFoundException cnfe ) { System.err.println( FACTORY_CLASS_NOT_FOUND_ERR_MSG ); //cnfe.printStackTrace(System.err); } catch( InstantiationException ie ) { System.err.println( UNABLE_TO_INSTANTIATE_FACTORY_ERR_MSG ); //ie.printStackTrace(System.err); } catch( IllegalAccessException iae ) { System.err.println( iae ); //iae.printStackTrace(System.err); } catch( ClassCastException cce ) { System.err.println( CLASS_NOT_A_BROWSER_FACTORY_IMPL_ERR_MSG + BROWSER_FACTORY_IMPL_INTERFACE_CLASSNAME ); //cce.printStackTrace(System.err); } } ]]>
Any implementation of a X3D browser that wishes to provide their own customised version of the browser factory should must subclass this class. In particular this is useful if the implementation needs to stay within the package defined by the application for other reasons.
A default implementation of this class is the DefaultBrowserFactoryImpl which is package access only.
]]>* If the frame name is a zero length string or null then it is assumed to be * located on the same HTML page as the applet. The index is the number of * the embed X3D browser starting from the top of the page. If there are * other non-X3D plugins embedded in the page these are not taken into * account in calculating the embed index. * * @param applet The applet reference to use * @param frameName The name of the frame to look into for the browser * @param index The embed index of the X3D browser in the page * @return A reference to the Browser implementation * @exception NotSupportedException The implementation does not support this * type of X3D browser. * @exception NoSuchBrowserException Could not locate a X3D browser on the * same page as the applet. * @exception ConnectionException An error occurred during the connecting * process */ ExternalBrowser getBrowser(Applet applet, String frameName, int index) throws NotSupportedException, NoSuchBrowserException, ConnectionException; /** * Get a reference to a browser that is located on a remote machine. This * a server application to send scene updates to a number of client browsers * located on remote machines. If there are a number of browsers running on * a remote machine, they can be differentiated by the port number they are * listening on. *
* There is no default port number for X3D browsers. * * @param address The address of the machine to connect to * @param port The port number on that machine to connect to. * @return A reference to the Browser implementation * @exception NotSupportedException The implementation does not support this * type of X3D browser. * @exception NoSuchBrowserException Could not locate a X3D browser on the * same page as the applet. * @exception UnknownHostException Could not find the machine named in the * address. * @exception ConnectionException An error occurred during the connecting * process */ ExternalBrowser getBrowser(InetAddress address, int port) throws NotSupportedException, NoSuchBrowserException, UnknownHostException, ConnectionException; ]]>
Generally this is used to provide a definition of an AWT component with a VRML/X3D display capability. There is no reason why this can not be used for other browser representations such as off-screen renderers or file savers.
]]>
A number of the methods in this application can take strings representing URLs. relative URL strings contained in URL fields of nodes or these method arguments are interpreted as follows:
]]>* This call is a nesting call which means subsequent calls to beginUpdate * are kept on a stack. No events will be released to the X3D browser * until as many endUpdates have been called as beginUpdate. *
* If no beginUpdate has been called before calling this method, it has * no effect. * * @exception InvalidBrowserException The dispose method has been called on * this browser reference. * @exception ConnectionException An error occurred in the connection to the * browser. */ void endUpdate() throws InvalidBrowserException; /** * Add a listener for browser events. Any changes in the browser will be * sent to this listener. The order of calling listeners is not guaranteed. * Checking is performed on whether the nominated listener is already * registered to ensure that multiple registration cannot take place. * Therefore it is possible to multiply register the one class * instance while only receiving one event. * * @param l The listener to add. * @exception NullPointerException If the provided listener reference is * null * @exception InvalidBrowserException The dispose method has been called on * this browser reference. * @exception ConnectionException An error occurred in the connection to the * browser. */ void addBrowserListener(BrowserListener l) throws InvalidBrowserException; /** * Remove a listener for browser events. After calling this method, the * listener will no longer receive events from this browser instance. If the * listener passed as an argument is not currently registered, the method * will silently exit. * * @param l The listener to remove * @exception NullPointerException If the provided listener reference is * null * @exception InvalidBrowserException The dispose method has been called on * this browser reference. * @exception ConnectionException An error occurred in the connection to the * browser. */ void removeBrowserListener(BrowserListener l) throws InvalidBrowserException; /** * Dispose the resources that are used by this instance. Should be called * just prior to leaving the application. */ void dispose(); ]]>
The exception that is thrown when a reference to any field is not valid. Generally used as a base class to more specific invalid field methods.
A field may be invalid for a number of reasons:
setUSE()
method resets all other fields to their default values and also releases
all child nodes.
* <!--
XML comment delimiters -->
around new comments.
* @param newComment initial comment, with no comment delimiters needed
*/
public CommentsBlock(String newComment)
{
initialize();
commentsList.add(newComment);
};
/** Constructor for CommentsBlock to initialize with initial comments array.
* No need to include <!--
XML comment delimiters -->
around new comments.
* @param newComments[] initial comments, with no comment delimiters needed
*/
public CommentsBlock(String newComments[])
{
initialize();
if ((newComments != null) && (newComments.length > 0))
commentsList.addAll(Arrays.asList(newComments));
};
/** Constructor for CommentsBlock to initialize with initial comments list.
* No need to include <!--
XML comment delimiters -->
around new comments.
* @param newCommentsList initial comments, with no comment delimiters needed
*/
public CommentsBlock(ArrayList<!--
XML comment delimiters -->
around new comments.
* @param newComment initial value, with no comment delimiters needed
* @return {@link CommentsBlock} - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public CommentsBlock addComments(String newComment)
{
commentsList.add(newComment);
return this;
}
/**
* Add comments as String[] array to this CommentsBlock.
* No need to include <!--
XML comment delimiters -->
around new comments.
* @param newComments array of comments, with no comment delimiters needed
* @return {@link CommentsBlock} - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public CommentsBlock addComments(String[] newComments)
{
commentsList.addAll(Arrays.asList(newComments));
return this;
}
/**
* Add comments array as ArrayList of String values to this CommentsBlock.
* No need to include <!--
XML comment delimiters -->
around new comments.
* @param newCommentsList list of comments, with no comment delimiters needed
* @return {@link CommentsBlock} - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
public CommentsBlock addComments(ArrayList<!--
XML comment delimiters -->
around new comments.
* @param newCommentsBlock block of comments to add, with no comment delimiters needed
* @return {@link CommentsBlock} - namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same node object).
*/
@Override
public CommentsBlock addComments(CommentsBlock newCommentsBlock)
{
commentsList.addAll(Arrays.asList(newCommentsBlock.toStrings()));
return this;
}
/**
* Provide CommentsBlock as string array.
* No need to include <!--
XML comment delimiters -->
around new comments.
* @return all comments
*/
public String[] toStrings()
{
return (String[]) commentsList.toArray();
}
/**
* Provide CommentsBlock as ArrayList of string(s).
* No need to include <!--
XML comment delimiters -->
around new comments.
* @return all comments
*/
public ArrayList<!--
and -->
, also replace invalid "--
" characters with "- -
".
* Typically only used internally when exporting via toStringX3D() methods to avoid (illegal) nested XML comments.
* @param newComment is comment to be cleaned
* @return cleaned-up string with no problematic XML comment characters embedded
*/
public static String cleanXmlCommentDelimiters (String newComment)
{
String result = newComment;
if (result == null)
result = new String();
if (result.contains("--"))
{
result = result.replaceAll("--","- -");
// TODO consider log entry
}
return result;
}
]]>