javax.media.j3d.LineAttributes Maven / Gradle / Ivy
Show all versions of java3d-core Show documentation
/*
* Copyright 1997-2008 Sun Microsystems, Inc. All Rights Reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Sun designates this
* particular file as subject to the "Classpath" exception as provided
* by Sun in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
* CA 95054 USA or visit www.sun.com if you need additional information or
* have any questions.
*
*/
package javax.media.j3d;
/**
* The LineAttributes object defines all rendering state that can be set
* as a component object of a Shape3D node.
* The line attributes that can be defined are:
*
- Pattern - specifies the pattern used to draw the line:
*
* - PATTERN_SOLID - draws a solid line with no pattern. This is
* the default.
*
*
- PATTERN_DASH - draws dashed lines. Ideally, these will be drawn with
* a repeating pattern of 8 pixels on and 8 pixels off.
*
*
- PATTERN_DOT - draws dotted lines. Ideally, these will be drawn with
* a repeating pattern of 1 pixel on and 7 pixels off.
*
*
- PATTERN_DASH_DOT - draws dashed-dotted lines. Ideally, these will be
* drawn with a repeating pattern of 7 pixels on, 4 pixels off, 1 pixel on,
* and 4 pixels off.
*
*
- PATTERN_USER_DEFINED - draws lines with a user-defined line pattern.
* See "User-defined Line Patterns," below.
*
*
*
- Antialiasing (enabled or disabled). By default, antialiasing
* is disabled.
*
*
* If antialiasing is enabled, the lines are considered transparent
* for rendering purposes. They are rendered with all the other transparent
* objects and adhere to the other transparency settings such as the
* View transparency sorting policy and the View depth buffer freeze
* transparent enable.
*
* - Width (in pixels). The default is a line width of one pixel.
*
*
* User-defined Line Patterns
*
* A user-defined line pattern is specified with a pattern mask and
* an optional scale factor.
*
* The Pattern Mask
*
* The pattern is specified
* using a 16-bit mask that specifies on and off segments. Bit 0 in
* the pattern mask corresponds to the first pixel of the line or line
* strip primitive. A value of 1 for a bit in the pattern mask indicates
* that the corresponding pixel is drawn, while a value of 0
* indicates that the corresponding pixel is not drawn. After all 16 bits
* in the pattern are used, the pattern is repeated.
*
* For example, a mask of 0x00ff defines a dashed line with a repeating
* pattern of 8 pixels on followed by 8 pixels off. A value of 0x0101
* defines a a dotted line with a repeating pattern of 1 pixel on and 7
* pixels off.
*
* The pattern continues around individual line segments of a line strip
* primitive. It is restarted at the beginning of each new line strip.
* For line array primitives, the pattern is restarted at the beginning
* of each line.
*
* The Scale Factor
*
* The pattern is multiplied by the scale factor such that each bit in
* the pattern mask corresponds to that many consecutive pixels.
* For example, a scale factor of 3 applied to a pattern mask of 0x001f
* would produce a repeating pattern of 15 pixels on followed by 33
* pixels off. The valid range for this attribute is [1,15]. Values
* outside this range are clamped.
*
* @see Appearance
* @see View
*/
public class LineAttributes extends NodeComponent {
/**
* Specifies that this LineAttributes object allows reading its
* line width information.
*/
public static final int
ALLOW_WIDTH_READ = CapabilityBits.LINE_ATTRIBUTES_ALLOW_WIDTH_READ;
/**
* Specifies that this LineAttributes object allows writing its
* line width information.
*/
public static final int
ALLOW_WIDTH_WRITE = CapabilityBits.LINE_ATTRIBUTES_ALLOW_WIDTH_WRITE;
/**
* Specifies that this LineAttributes object allows reading its
* line pattern information.
*/
public static final int
ALLOW_PATTERN_READ = CapabilityBits.LINE_ATTRIBUTES_ALLOW_PATTERN_READ;
/**
* Specifies that this LineAttributes object allows writing its
* line pattern information.
*/
public static final int
ALLOW_PATTERN_WRITE = CapabilityBits.LINE_ATTRIBUTES_ALLOW_PATTERN_WRITE;
/**
* Specifies that this LineAttributes object allows reading its
* line antialiasing flag.
*/
public static final int
ALLOW_ANTIALIASING_READ = CapabilityBits.LINE_ATTRIBUTES_ALLOW_ANTIALIASING_READ;
/**
* Specifies that this LineAttributes object allows writing its
* line antialiasing flag.
*/
public static final int
ALLOW_ANTIALIASING_WRITE = CapabilityBits.LINE_ATTRIBUTES_ALLOW_ANTIALIASING_WRITE;
/**
* Draw solid lines with no pattern.
* @see #setLinePattern
*/
public static final int PATTERN_SOLID = 0;
/**
* Draw dashed lines. Ideally, these will be drawn with
* a repeating pattern of 8 pixels on and 8 pixels off.
* @see #setLinePattern
*/
public static final int PATTERN_DASH = 1;
/**
* Draw dotted lines. Ideally, these will be drawn with
* a repeating pattern of 1 pixel on and 7 pixels off.
* @see #setLinePattern
*/
public static final int PATTERN_DOT = 2;
/**
* Draw dashed-dotted lines. Ideally, these will be drawn with
* a repeating pattern of 7 pixels on, 4 pixels off, 1 pixel on,
* and 4 pixels off.
* @see #setLinePattern
*/
public static final int PATTERN_DASH_DOT = 3;
/**
* Draw lines with a user-defined line pattern. The line pattern
* is specified with a pattern mask and scale factor.
* @see #setLinePattern
* @see #setPatternMask
* @see #setPatternScaleFactor
*
* @since Java 3D 1.2
*/
public static final int PATTERN_USER_DEFINED = 4;
// Array for setting default read capabilities
private static final int[] readCapabilities = {
ALLOW_ANTIALIASING_READ,
ALLOW_PATTERN_READ,
ALLOW_WIDTH_READ
};
/**
* Constructs a LineAttributes object with default parameters.
* The default values are as follows:
*
* line width : 1
* line pattern : PATTERN_SOLID
* pattern mask : 0xffff
* pattern scale factor : 1
* line antialiasing : false
*
*/
public LineAttributes(){
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
}
/**
* Constructs a LineAttributes object with specified values.
* @param lineWidth the width of lines in pixels
* @param linePattern the line pattern, one of PATTERN_SOLID,
* PATTERN_DASH, PATTERN_DOT, or PATTERN_DASH_DOT
* @param lineAntialiasing flag to set line antialising ON or OFF
*/
public LineAttributes(float lineWidth, int linePattern,
boolean lineAntialiasing){
if (linePattern < PATTERN_SOLID || linePattern > PATTERN_DASH_DOT)
throw new IllegalArgumentException(J3dI18N.getString("LineAttributes0"));
// set default read capabilities
setDefaultReadCapabilities(readCapabilities);
((LineAttributesRetained)this.retained).initLineWidth(lineWidth);
((LineAttributesRetained)this.retained).initLinePattern(linePattern);
((LineAttributesRetained)this.retained).initLineAntialiasingEnable(lineAntialiasing);
}
/**
* Sets the line width for this LineAttributes component object.
* @param lineWidth the width, in pixels, of line primitives
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setLineWidth(float lineWidth) {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_WIDTH_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes1"));
if (isLive())
((LineAttributesRetained)this.retained).setLineWidth(lineWidth);
else
((LineAttributesRetained)this.retained).initLineWidth(lineWidth);
}
/**
* Gets the line width for this LineAttributes component object.
* @return the width, in pixels, of line primitives
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public float getLineWidth() {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_WIDTH_READ))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes2"));
return ((LineAttributesRetained)this.retained).getLineWidth();
}
/**
* Sets the line pattern for this LineAttributes component object.
* @param linePattern the line pattern to be used, one of:
* PATTERN_SOLID, PATTERN_DASH, PATTERN_DOT, PATTERN_DASH_DOT, or
* PATTERN_USER_DEFINED.
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public void setLinePattern(int linePattern) {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_PATTERN_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes3"));
if (linePattern < PATTERN_SOLID || linePattern > PATTERN_USER_DEFINED)
throw new IllegalArgumentException(J3dI18N.getString("LineAttributes4"));
if (isLive())
((LineAttributesRetained)this.retained).setLinePattern(linePattern);
else
((LineAttributesRetained)this.retained).initLinePattern(linePattern);
}
/**
* Gets the line pattern for this LineAttributes component object.
* @return the line pattern
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public int getLinePattern() {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_PATTERN_READ))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes5"));
return ((LineAttributesRetained)this.retained).getLinePattern();
}
/**
* Sets the line pattern mask to the specified value. This is
* used when the linePattern attribute is set to
* PATTERN_USER_DEFINED. In this mode, the pattern is specified
* using a 16-bit mask that specifies on and off segments. Bit 0
* in the pattern mask corresponds to the first pixel of the line
* or line strip primitive. A value of 1 for a bit in the pattern
* mask indicates that the corresponding pixel is drawn, while a
* value of 0 indicates that the corresponding pixel is not drawn.
* After all 16 bits in the pattern are used, the pattern is
* repeated. For example, a mask of 0x00ff defines a dashed line
* with a repeating pattern of 8 pixels on followed by 8 pixels
* off. A value of 0x0101 defines a a dotted line with a
* repeating pattern of 1 pixel on and 7 pixels off
*
* The pattern continues around individual line segments of a line
* strip primitive. It is restarted at the beginning of each new
* line strip. For line array primitives, the pattern is
* restarted at the beginning of each line.
* @param mask the new line pattern mask
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @see #setPatternScaleFactor
*
* @since Java 3D 1.2
*/
public void setPatternMask(int mask) {
if (isLiveOrCompiled() &&
!this.getCapability(ALLOW_PATTERN_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes8"));
if (isLive())
((LineAttributesRetained)this.retained).setPatternMask(mask);
else
((LineAttributesRetained)this.retained).initPatternMask(mask);
}
/**
* Retrieves the line pattern mask.
* @return the line pattern mask
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*
* @since Java 3D 1.2
*/
public int getPatternMask() {
if (isLiveOrCompiled() &&
!this.getCapability(ALLOW_PATTERN_READ))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes9"));
return ((LineAttributesRetained)this.retained).getPatternMask();
}
/**
* Sets the line pattern scale factor to the specified value.
* This is used in conjunction with the patternMask when the
* linePattern attribute is set to PATTERN_USER_DEFINED. The
* pattern is multiplied by the scale factor such that each bit in
* the pattern mask corresponds to that many consecutive pixels.
* For example, a scale factor of 3 applied to a pattern mask of
* 0x001f would produce a repeating pattern of 15 pixels on
* followed by 33 pixels off. The valid range for this attribute
* is [1,15]. Values outside this range are clamped.
* @param scaleFactor the new line pattern scale factor
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @see #setPatternMask
*
* @since Java 3D 1.2
*/
public void setPatternScaleFactor(int scaleFactor) {
if (isLiveOrCompiled() &&
!this.getCapability(ALLOW_PATTERN_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes10"));
if (isLive())
((LineAttributesRetained)this.retained).setPatternScaleFactor(scaleFactor);
else
((LineAttributesRetained)this.retained).initPatternScaleFactor(scaleFactor);
}
/**
* Retrieves the line pattern scale factor.
* @return the line pattern scale factor
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*
* @since Java 3D 1.2
*/
public int getPatternScaleFactor() {
if (isLiveOrCompiled() &&
!this.getCapability(ALLOW_PATTERN_READ))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes11"));
return ((LineAttributesRetained)this.retained).getPatternScaleFactor();
}
/**
* Enables or disables line antialiasing
* for this LineAttributes component object.
*
* If antialiasing is enabled, the lines are considered transparent
* for rendering purposes. They are rendered with all the other
* transparent objects and adhere to the other transparency settings
* such as the View transparency sorting policy and the View depth buffer
* freeze transparent enable.
*
* @param state true or false to enable or disable line antialiasing
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
* @see View
*/
public void setLineAntialiasingEnable(boolean state) {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_ANTIALIASING_WRITE))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes6"));
if (isLive())
((LineAttributesRetained)this.retained).setLineAntialiasingEnable(state);
else
((LineAttributesRetained)this.retained).initLineAntialiasingEnable(state);
}
/**
* Retrieves the state of the line antialiasing flag.
* @return true if line antialiasing is enabled,
* false if line antialiasing is disabled
* @exception CapabilityNotSetException if appropriate capability is
* not set and this object is part of live or compiled scene graph
*/
public boolean getLineAntialiasingEnable() {
if (isLiveOrCompiled())
if(!this.getCapability(ALLOW_ANTIALIASING_READ))
throw new CapabilityNotSetException(J3dI18N.getString("LineAttributes7"));
return ((LineAttributesRetained)this.retained).getLineAntialiasingEnable();
}
/**
* Creates a retained mode LineAttributesRetained object that this
* LineAttributes component object will point to.
*/
@Override
void createRetained() {
this.retained = new LineAttributesRetained();
this.retained.setSource(this);
}
/**
* @deprecated replaced with cloneNodeComponent(boolean forceDuplicate)
*/
@Override
public NodeComponent cloneNodeComponent() {
LineAttributes la = new LineAttributes();
la.duplicateNodeComponent(this);
return la;
}
/**
* Copies all node information from originalNodeComponent into
* the current node. This method is called from the
* duplicateNode method. This routine does
* the actual duplication of all "local data" (any data defined in
* this object).
*
* @param originalNodeComponent the original node to duplicate.
* @param forceDuplicate when set to true, causes the
* duplicateOnCloneTree flag to be ignored. When
* false, the value of each node's
* duplicateOnCloneTree variable determines whether
* NodeComponent data is duplicated or copied.
*
* @see Node#cloneTree
* @see NodeComponent#setDuplicateOnCloneTree
*/
@Override
void duplicateAttributes(NodeComponent originalNodeComponent,
boolean forceDuplicate) {
super.duplicateAttributes(originalNodeComponent,
forceDuplicate);
LineAttributesRetained attr = (LineAttributesRetained)
originalNodeComponent.retained;
LineAttributesRetained rt = (LineAttributesRetained) retained;
rt.initLineWidth(attr.getLineWidth());
rt.initLinePattern(attr.getLinePattern());
rt.initLineAntialiasingEnable(attr.getLineAntialiasingEnable());
rt.initPatternMask(attr.getPatternMask());
rt.initPatternScaleFactor(attr.getPatternScaleFactor());
}
}