background.java

JAVA3D矩陈的相关类

     * drawing any objects in the scene.  If the image is smaller
     * than the window,
     * then that portion of the window not covered by the image is
     * filled with the background color.
     *
     * @param image new pixel array object used as the background image
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     *
     * @exception IllegalSharingException if this Background is live and
     * the specified image is being used by a Canvas3D as an off-screen buffer.
     *
     * @exception IllegalSharingException if this Background is
     * being used by an immediate mode context and
     * the specified image is being used by a Canvas3D as an off-screen buffer.
     *
     * @exception IllegalArgumentException if the image class of the specified
     * ImageComponent2D is ImageClass.NIO_IMAGE_BUFFER.
     */
    public void setImage(ImageComponent2D image) {
        if (isLiveOrCompiled())
         if(!this.getCapability(ALLOW_IMAGE_WRITE))
           throw new CapabilityNotSetException(J3dI18N.getString("Background3"));

        BackgroundRetained bgRetained = (BackgroundRetained)this.retained;

        if((image != null) && 
                (image.getImageClass() == ImageComponent.ImageClass.NIO_IMAGE_BUFFER)) {     
            throw new IllegalArgumentException(J3dI18N.getString("Background14"));
        }

        // Do illegal sharing check
        if(image != null) {
            ImageComponent2DRetained imageRetained = (ImageComponent2DRetained) image.retained;
            if(imageRetained.getUsedByOffScreen()) {
                if(isLive()) {
                    throw new IllegalSharingException(J3dI18N.getString("Background12"));
                }
                if(bgRetained.getInImmCtx()) {
                    throw new IllegalSharingException(J3dI18N.getString("Background13"));
                }
            }
        }
        
	if (isLive())
	    bgRetained.setImage(image);
	else
	    bgRetained.initImage(image);
    }

    /**
     * Retrieves the background image.
     * @return the current background image
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public ImageComponent2D getImage() {
        if (isLiveOrCompiled())
         if(!this.getCapability(ALLOW_IMAGE_READ))
           throw new CapabilityNotSetException(J3dI18N.getString("Background4"));

	return ((BackgroundRetained)this.retained).getImage();
    }

    /**
     * Sets the image scale mode for this Background node.
     *
     * @param imageScaleMode the new image scale mode, one of:
     * SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX, SCALE_FIT_ALL,
     * SCALE_REPEAT, or SCALE_NONE_CENTER.
     *
     * @exception IllegalArgumentException if <code>imageScaleMode</code>
     * is a value other than SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX,
     * SCALE_FIT_ALL, SCALE_REPEAT, or SCALE_NONE_CENTER.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     *
     * @since Java 3D 1.3
     */
    public void setImageScaleMode(int imageScaleMode) {
        if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_IMAGE_SCALE_MODE_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("Background9"));

	switch (imageScaleMode) {
	case SCALE_NONE:
	case SCALE_FIT_MIN:
	case SCALE_FIT_MAX:
	case SCALE_FIT_ALL:
	case SCALE_REPEAT:
	case SCALE_NONE_CENTER:
	    break;
	default:
	    throw new IllegalArgumentException(J3dI18N.getString("Background11"));
	}
	
	if (isLive())
	    ((BackgroundRetained)this.retained).setImageScaleMode(imageScaleMode);
	else
	    ((BackgroundRetained)this.retained).initImageScaleMode(imageScaleMode);
	
    }

    /**
     * Retrieves the current image scale mode.
     * @return the current image scale mode, one of:
     * SCALE_NONE, SCALE_FIT_MIN, SCALE_FIT_MAX, SCALE_FIT_ALL,
     * SCALE_REPEAT, or SCALE_NONE_CENTER.
     *
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     *
     * @since Java 3D 1.3
     */
    public int getImageScaleMode() {
        if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_IMAGE_SCALE_MODE_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("Background10"));
	return ((BackgroundRetained)this.retained).getImageScaleMode();
    }

    /**
     * Sets the background geometry to the specified BranchGroup node.
     * If non-null, this background geometry is drawn on top of
     * the background color and image using a projection
     * matrix that essentially puts the geometry at infinity.  The geometry
     * should be pre-tessellated onto a unit sphere.
     * @param branch the root of the background geometry
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     * @exception IllegalSharingException if the BranchGroup node
     * is a child of any Group node, or is already attached to a Locale,
     * or is already referenced by another Background node.
     * @exception IllegalSceneGraphException if specified branch graph
     * contains an illegal node.
     */
    public void setGeometry(BranchGroup branch) {
        if (isLiveOrCompiled())
         if(!this.getCapability(ALLOW_GEOMETRY_WRITE))
           throw new CapabilityNotSetException(J3dI18N.getString("Background5"));

	if (isLive())
	    ((BackgroundRetained)this.retained).setGeometry(branch);
	else
	    ((BackgroundRetained)this.retained).initGeometry(branch);
    }

    /**
     * Retrieves the background geometry.
     * @return the BranchGroup node that is the root of the background
     *  geometry
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */
    public BranchGroup getGeometry() {
        if (isLiveOrCompiled())
         if(!this.getCapability(ALLOW_GEOMETRY_READ))
           throw new CapabilityNotSetException(J3dI18N.getString("Background6"));

	return ((BackgroundRetained)this.retained).getGeometry();
    }

    /**
     * Set the Background's application region to the specified bounds.
     * This is used when the application bounding leaf is set to null.
     * @param region the bounds that contains the Background's new application
     * region.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */  
    public void setApplicationBounds(Bounds region) {
        if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_APPLICATION_BOUNDS_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("Background7"));

	if (isLive())
	    ((BackgroundRetained)this.retained).setApplicationBounds(region);
	else
	    ((BackgroundRetained)this.retained).initApplicationBounds(region);
    }

    /**  
     * Retrieves the Background node's application bounds.
     * @return this Background's application bounds information
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */  
    public Bounds getApplicationBounds() {
        if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_APPLICATION_BOUNDS_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("Background8"));

	return ((BackgroundRetained)this.retained).getApplicationBounds();
    }

    /**
     * Set the Background's application region to the specified bounding leaf.
     * When set to a value other than null, this overrides the application
     * bounds object.
     * @param region the bounding leaf node used to specify the Background
     * node's new application region.
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */  
    public void setApplicationBoundingLeaf(BoundingLeaf region) {
        if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_APPLICATION_BOUNDS_WRITE))
		throw new CapabilityNotSetException(J3dI18N.getString("Background7"));

	if (isLive())
	    ((BackgroundRetained)this.retained).setApplicationBoundingLeaf(region);
	else
	    ((BackgroundRetained)this.retained).initApplicationBoundingLeaf(region);
    }

    /**  
     * Retrieves the Background node's application bounding leaf.
     * @return this Background's application bounding leaf information
     * @exception CapabilityNotSetException if appropriate capability is
     * not set and this object is part of live or compiled scene graph
     */  
    public BoundingLeaf getApplicationBoundingLeaf() {
        if (isLiveOrCompiled())
	    if(!this.getCapability(ALLOW_APPLICATION_BOUNDS_READ))
		throw new CapabilityNotSetException(J3dI18N.getString("Background8"));

	return ((BackgroundRetained)this.retained).getApplicationBoundingLeaf();
    }

    /**
     * Creates the retained mode BackgroundRetained object that this
     * Background component object will point to.
     */
    void createRetained() {
        this.retained = new BackgroundRetained();
        this.retained.setSource(this);
    }

 
   /**
     * Creates a new instance of the node.  This routine is called
     * by <code>cloneTree</code> to duplicate the current node.
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.<br>
     * Background geometry will not clone in this operation. 
     * It is the user's responsibility
     * to call <code>cloneTree</code> on that branchGroup.
     *
     * @see Node#cloneTree
     * @see Node#cloneNode
     * @see Node#duplicateNode
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    public Node cloneNode(boolean forceDuplicate) {
        Background b = new Background();
        b.duplicateNode(this, forceDuplicate);
        return b;
    }

    
    /**
     * Copies all node information from <code>originalNode</code> into
     * the current node.  This method is called from the
     * <code>cloneNode</code> method which is, in turn, called by the
     * <code>cloneTree</code> method.
     * <P>
     * For any <code>NodeComponent</code> objects
     * contained by the object being duplicated, each <code>NodeComponent</code>
     * object's <code>duplicateOnCloneTree</code> value is used to determine
     * whether the <code>NodeComponent</code> should be duplicated in the new node
     * or if just a reference to the current node should be placed in the
     * new node.  This flag can be overridden by setting the
     * <code>forceDuplicate</code> parameter in the <code>cloneTree</code>
     * method to <code>true</code>.
     *
     * <br>
     * NOTE: Applications should <i>not</i> call this method directly.
     * It should only be called by the cloneNode method.
     *
     * @param originalNode the original node to duplicate.
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.
     * @exception ClassCastException if originalNode is not an instance of 
     *  <code>Background</code>
     *
     * @see Node#cloneTree
     * @see Node#cloneNode
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    public void duplicateNode(Node originalNode, boolean
			      forceDuplicate) {
	checkDuplicateNode(originalNode, forceDuplicate);
    }


   /**
     * Copies all Background information from
     * <code>originalNode</code> into
     * the current node.  This method is called from the
     * <code>cloneNode</code> method which is, in turn, called by the
     * <code>cloneTree</code> method.<P> 
     *
     * @param originalNode the original node to duplicate
     * @param forceDuplicate when set to <code>true</code>, causes the
     *  <code>duplicateOnCloneTree</code> flag to be ignored.  When
     *  <code>false</code>, the value of each node's
     *  <code>duplicateOnCloneTree</code> variable determines whether
     *  NodeComponent data is duplicated or copied.
     *
     * @exception RestrictedAccessException if this object is part of a live
     *  or compiled scenegraph.
     *
     * @see Node#duplicateNode
     * @see Node#cloneTree
     * @see NodeComponent#setDuplicateOnCloneTree
     */
    void duplicateAttributes(Node originalNode, boolean forceDuplicate) {
        super.duplicateAttributes(originalNode, forceDuplicate);

	BackgroundRetained attr = (BackgroundRetained) originalNode.retained;
	BackgroundRetained rt = (BackgroundRetained) retained;

	Color3f c = new Color3f();
	attr.getColor(c);
	rt.initColor(c);
	rt.initApplicationBounds(attr.getApplicationBounds());
	rt.initGeometry(attr.getGeometry());
	rt.initImage((ImageComponent2D) getNodeComponent(
					     attr.getImage(),
					     forceDuplicate, 
					     originalNode.nodeHashtable));

	// this will be updated in updateNodeReferences
	rt.initApplicationBoundingLeaf(attr.getApplicationBoundingLeaf());
    }

   
    /**
     * Callback used to allow a node to check if any scene graph objects
     * referenced
     * by that node have been duplicated via a call to <code>cloneTree</code>.
     * This method is called by <code>cloneTree</code> after all nodes in
     * the sub-graph have been duplicated. The cloned Leaf node's method
     * will be called and the Leaf node can then look up any object references
     * by using the <code>getNewObjectReference</code> method found in the
     * <code>NodeReferenceTable</code> object.  If a match is found, a
     * reference to the corresponding object in the newly cloned sub-graph
     * is returned.  If no corresponding reference is found, either a
     * DanglingReferenceException is thrown or a reference to the original
     * object is returned depending on the value of the
     * <code>allowDanglingReferences</code> parameter passed in the
     * <code>cloneTree</code> call.
     * <p>
     * NOTE: Applications should <i>not</i> call this method directly.
     * It should only be called by the cloneTree method.
     *
     * @param referenceTable a NodeReferenceTableObject that contains the
     *  <code>getNewObjectReference</code> method needed to search for
     *  new object instances
     *
     * @see NodeReferenceTable
     * @see Node#cloneTree
     * @see DanglingReferenceException
     */
    public void updateNodeReferences(NodeReferenceTable referenceTable) {
        super.updateNodeReferences(referenceTable);

	BackgroundRetained rt = (BackgroundRetained) retained;
	BoundingLeaf bl=  rt.getApplicationBoundingLeaf();

        if (bl != null) {
            Object o = referenceTable.getNewObjectReference(bl);
            rt.initApplicationBoundingLeaf((BoundingLeaf) o);
        }
    }
}