Interface Background
- All Superinterfaces:
X3DBackgroundNode
,X3DBindableNode
,X3DChildNode
,X3DNode
- All Known Implementing Classes:
Background
Background simulates ground and sky, using vertical arrays of wraparound color values.
Warning: this is an abstract interface that cannot be instantiated as a concrete object. Java programmers typically only need to use concrete objects provided by the
Package hint: This interface is defined by the X3D Java Language Binding Specification for the Scene Authoring Interface (SAI).
Warning: this is an abstract interface that cannot be instantiated as a concrete object. Java programmers typically only need to use concrete objects provided by the
org.web3d.x3d.jsail
classes.
Background node tooltip: [X3DBackgroundNode] Background simulates ground and sky, using vertical arrays of wraparound color values. Background can also provide url addresses for backdrop textures on all six sides.
- Hint: Background, Fog, GeoViewpoint, NavigationInfo, OrthoViewpoint, TextureBackground and Viewpoint are bindable nodes, meaning that no more than one of each node type can be active at a given time.
- Warning: results are undefined if a bindable node (Background, Fog, NavigationInfo, OrthoViewpoint, TextureBackground, Viewpoint) is a contained descendant node of either LOD or Switch. Avoid this authoring pattern.
- Hint: Background node is not sensed by LoadSensor due to node typing and multiple-image ambiguity, alternatively utilize TextureBackground node with multiple ImageTexture nodes each referenced inside LoadSensor.
- Hint: X3D Example Archives, Basic, Universal Media Panoramas https://www.web3d.org/x3d/content/examples/Basic/UniversalMediaPanoramas
Package hint: This interface is defined by the X3D Java Language Binding Specification for the Scene Authoring Interface (SAI).
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionString[]
Provide array of String results from inputOutput MFString field named backUrl.double
Provide double value in seconds from outputOnly SFTime field named bindTime.String[]
Provide array of String results from inputOutput MFString field named bottomUrl.String[]
Provide array of String results from inputOutput MFString field named frontUrl.float[]
Provide array of float results unit axis, angle (in radians) within allowed range of [0,1.5708] from inputOutput MFFloat field named groundAngle.float[]
Provide array of 3-tuple float results using RGB values [0..1] using RGB values [0..1] from inputOutput MFColor field named groundColor.boolean
Provide boolean value from outputOnly SFBool field named isBound.String[]
Provide array of String results from inputOutput MFString field named leftUrl.Provide org.web3d.x3d.sai.Core.X3DMetadataObject instance (using a properly typed node) from inputOutput SFNode field metadata.String[]
Provide array of String results from inputOutput MFString field named rightUrl.float[]
Provide array of float results unit axis, angle (in radians) within allowed range of [0,3.1416] from inputOutput MFFloat field named skyAngle.float[]
Provide array of 3-tuple float results using RGB values [0..1] using RGB values [0..1] from inputOutput MFColor field named skyColor.String[]
Provide array of String results from inputOutput MFString field named topUrl.float
Provide float value within allowed range of [0,1] from inputOutput SFFloat field named transparency.setBackUrl
(String[] newValue) Accessor method to assign String array to inputOutput MFString field named backUrl.setBottomUrl
(String[] newValue) Accessor method to assign String array to inputOutput MFString field named bottomUrl.setFrontUrl
(String[] newValue) Accessor method to assign String array to inputOutput MFString field named frontUrl.setGroundAngle
(float[] newValue) Accessor method to assign float array unit axis, angle (in radians) to inputOutput MFFloat field named groundAngle.setGroundColor
(float[] newValue) Accessor method to assign 3-tuple float array using RGB values [0..1] to inputOutput MFColor field named groundColor.setLeftUrl
(String[] newValue) Accessor method to assign String array to inputOutput MFString field named leftUrl.setMetadata
(X3DMetadataObject newValue) Accessor method to assign org.web3d.x3d.sai.Core.X3DMetadataObject instance (using a properly typed node) to inputOutput SFNode field metadata.setRightUrl
(String[] newValue) Accessor method to assign String array to inputOutput MFString field named rightUrl.setSkyAngle
(float[] newValue) Accessor method to assign float array unit axis, angle (in radians) to inputOutput MFFloat field named skyAngle.setSkyColor
(float[] newValue) Accessor method to assign 3-tuple float array using RGB values [0..1] to inputOutput MFColor field named skyColor.Accessor method to assign String array to inputOutput MFString field named topUrl.setTransparency
(float newValue) Accessor method to assign float value to inputOutput SFFloat field named transparency.
-
Method Details
-
getBackUrl
String[] getBackUrl()Provide array of String results from inputOutput MFString field named backUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Returns:
- value of backUrl field
-
setBackUrl
Accessor method to assign String array to inputOutput MFString field named backUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Parameters:
newValue
- is new value for the backUrl field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getBindTime
double getBindTime()Provide double value in seconds from outputOnly SFTime field named bindTime.
Tooltip: event sent when node becomes active/inactive.- Warning: it is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
- Specified by:
getBindTime
in interfaceX3DBackgroundNode
- Specified by:
getBindTime
in interfaceX3DBindableNode
- Returns:
- value of bindTime field
-
getBottomUrl
String[] getBottomUrl()Provide array of String results from inputOutput MFString field named bottomUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Returns:
- value of bottomUrl field
-
setBottomUrl
Accessor method to assign String array to inputOutput MFString field named bottomUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Parameters:
newValue
- is new value for the bottomUrl field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getFrontUrl
String[] getFrontUrl()Provide array of String results from inputOutput MFString field named frontUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Returns:
- value of frontUrl field
-
setFrontUrl
Accessor method to assign String array to inputOutput MFString field named frontUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Parameters:
newValue
- is new value for the frontUrl field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getGroundAngle
float[] getGroundAngle()Provide array of float results unit axis, angle (in radians) within allowed range of [0,1.5708] from inputOutput MFFloat field named groundAngle.
Tooltip: [0,pi/2] The angle array values increase from 0.0 nadir (straight down) to pi/2=1.570796 (horizon).- Warning: you must have one more groundColor value than groundAngle values.
- Warning: colors at groundAngle=0 are ignored. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Hint: radian units for angular measure https://en.wikipedia.org/wiki/Radian
- Specified by:
getGroundAngle
in interfaceX3DBackgroundNode
- Returns:
- value of groundAngle field
-
setGroundAngle
Accessor method to assign float array unit axis, angle (in radians) to inputOutput MFFloat field named groundAngle.
Tooltip: [0,pi/2] The angle array values increase from 0.0 nadir (straight down) to pi/2=1.570796 (horizon).- Warning: you must have one more groundColor value than groundAngle values.
- Warning: colors at groundAngle=0 are ignored. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Hint: radian units for angular measure https://en.wikipedia.org/wiki/Radian
- Specified by:
setGroundAngle
in interfaceX3DBackgroundNode
- Parameters:
newValue
- is new value for the groundAngle field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getGroundColor
float[] getGroundColor()Provide array of 3-tuple float results using RGB values [0..1] using RGB values [0..1] from inputOutput MFColor field named groundColor.
Tooltip: Color of the ground at the various angles on the ground partial sphere. First value is color of ground at 0.0 radians representing the nadir (straight down).- Hint: setting the same color at two consecutive angles produces a solid color band.
- Warning: you must have one more groundColor value than groundAngle values. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Hint: X3D Scene Authoring Hints, Color https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Color
- Specified by:
getGroundColor
in interfaceX3DBackgroundNode
- Returns:
- value of groundColor field
-
setGroundColor
Accessor method to assign 3-tuple float array using RGB values [0..1] to inputOutput MFColor field named groundColor.
Tooltip: Color of the ground at the various angles on the ground partial sphere. First value is color of ground at 0.0 radians representing the nadir (straight down).- Hint: setting the same color at two consecutive angles produces a solid color band.
- Warning: you must have one more groundColor value than groundAngle values. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Hint: X3D Scene Authoring Hints, Color https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Color
- Specified by:
setGroundColor
in interfaceX3DBackgroundNode
- Parameters:
newValue
- is new value for the groundColor field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getIsBound
boolean getIsBound()Provide boolean value from outputOnly SFBool field named isBound.
Tooltip: event true sent when node becomes active, event false sent when unbound by another node.- Hint: paired node operations can be established by connecting set_bind and isBound fields of corresponding bindable nodes.
- Warning: it is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
- Specified by:
getIsBound
in interfaceX3DBackgroundNode
- Specified by:
getIsBound
in interfaceX3DBindableNode
- Returns:
- value of isBound field
-
getLeftUrl
String[] getLeftUrl()Provide array of String results from inputOutput MFString field named leftUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Returns:
- value of leftUrl field
-
setLeftUrl
Accessor method to assign String array to inputOutput MFString field named leftUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Parameters:
newValue
- is new value for the leftUrl field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getMetadata
X3DMetadataObject getMetadata()Provide org.web3d.x3d.sai.Core.X3DMetadataObject instance (using a properly typed node) from inputOutput SFNode field metadata.
Tooltip: [X3DMetadataObject] Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.- Hint: X3D Architecture 7.2.4 Metadata https://www.web3d.org/specifications/X3Dv4/ISO-IEC19775-1v4-IS /Part01/components/core.html#Metadata
- Specified by:
getMetadata
in interfaceX3DBackgroundNode
- Specified by:
getMetadata
in interfaceX3DBindableNode
- Specified by:
getMetadata
in interfaceX3DChildNode
- Specified by:
getMetadata
in interfaceX3DNode
- Returns:
- value of metadata field
- See Also:
-
setMetadata
Accessor method to assign org.web3d.x3d.sai.Core.X3DMetadataObject instance (using a properly typed node) to inputOutput SFNode field metadata.
Tooltip: [X3DMetadataObject] Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.- Hint: X3D Architecture 7.2.4 Metadata https://www.web3d.org/specifications/X3Dv4/ISO-IEC19775-1v4-IS /Part01/components/core.html#Metadata
- Specified by:
setMetadata
in interfaceX3DBackgroundNode
- Specified by:
setMetadata
in interfaceX3DBindableNode
- Specified by:
setMetadata
in interfaceX3DChildNode
- Specified by:
setMetadata
in interfaceX3DNode
- Parameters:
newValue
- is new value for the metadata field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).- See Also:
-
getRightUrl
String[] getRightUrl()Provide array of String results from inputOutput MFString field named rightUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Returns:
- value of rightUrl field
-
setRightUrl
Accessor method to assign String array to inputOutput MFString field named rightUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Parameters:
newValue
- is new value for the rightUrl field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getSkyAngle
float[] getSkyAngle()Provide array of float results unit axis, angle (in radians) within allowed range of [0,3.1416] from inputOutput MFFloat field named skyAngle.
Tooltip: [0,pi] The angle array values increase from 0.0 zenith (straight up) to pi/2=1.570796 (horizon) to pi=3.14159 (nadir).- Warning: you must have one more skyColor value than skyAngle values.
- Warning: colors at skyAngle=0 are ignored. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Hint: radian units for angular measure https://en.wikipedia.org/wiki/Radian
- Specified by:
getSkyAngle
in interfaceX3DBackgroundNode
- Returns:
- value of skyAngle field
-
setSkyAngle
Accessor method to assign float array unit axis, angle (in radians) to inputOutput MFFloat field named skyAngle.
Tooltip: [0,pi] The angle array values increase from 0.0 zenith (straight up) to pi/2=1.570796 (horizon) to pi=3.14159 (nadir).- Warning: you must have one more skyColor value than skyAngle values.
- Warning: colors at skyAngle=0 are ignored. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Hint: radian units for angular measure https://en.wikipedia.org/wiki/Radian
- Specified by:
setSkyAngle
in interfaceX3DBackgroundNode
- Parameters:
newValue
- is new value for the skyAngle field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getSkyColor
float[] getSkyColor()Provide array of 3-tuple float results using RGB values [0..1] using RGB values [0..1] from inputOutput MFColor field named skyColor.
Tooltip: Color of the sky at various angles on the sky sphere. First value is color of sky at 0.0 radians representing the zenith (straight up).- Hint: setting the same color at two consecutive angles produces a solid color band.
- Warning: you must have one more skyColor value than skyAngle values. Interchange profile
- Hint: only one color might be rendered, others can be ignored.
- Hint: X3D Scene Authoring Hints, Color https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Color
- Specified by:
getSkyColor
in interfaceX3DBackgroundNode
- Returns:
- value of skyColor field
-
setSkyColor
Accessor method to assign 3-tuple float array using RGB values [0..1] to inputOutput MFColor field named skyColor.
Tooltip: Color of the sky at various angles on the sky sphere. First value is color of sky at 0.0 radians representing the zenith (straight up).- Hint: setting the same color at two consecutive angles produces a solid color band.
- Warning: you must have one more skyColor value than skyAngle values. Interchange profile
- Hint: only one color might be rendered, others can be ignored.
- Hint: X3D Scene Authoring Hints, Color https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#Color
- Specified by:
setSkyColor
in interfaceX3DBackgroundNode
- Parameters:
newValue
- is new value for the skyColor field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getTopUrl
String[] getTopUrl()Provide array of String results from inputOutput MFString field named topUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Returns:
- value of topUrl field
-
setTopUrl
Accessor method to assign String array to inputOutput MFString field named topUrl.
Tooltip: Image background panorama between ground/sky backdrop and scene's geometry.- Hint: MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
- Hint: alternative XML encoding for quotation mark " is " (which is an example of a character entity).
- Warning: strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https url addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
- Hint: can replace embedded blank(s) in url queries with %20 for each blank character. Interchange profile
- Hint: this field may be ignored, applying the default value regardless.
- Parameters:
newValue
- is new value for the topUrl field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-
getTransparency
float getTransparency()Provide float value within allowed range of [0,1] from inputOutput SFFloat field named transparency.
Tooltip: [0,1] how "clear" the background is, allows underlying page to show through: 1.0 is completely transparent, 0.0 is completely opaque. Interchange profile- Hint: transparency < .5 opaque, transparency > .5 transparent.
- Specified by:
getTransparency
in interfaceX3DBackgroundNode
- Returns:
- value of transparency field
-
setTransparency
Accessor method to assign float value to inputOutput SFFloat field named transparency.
Tooltip: [0,1] how "clear" the background is, allows underlying page to show through: 1.0 is completely transparent, 0.0 is completely opaque. Interchange profile- Hint: transparency < .5 opaque, transparency > .5 transparent.
- Specified by:
setTransparency
in interfaceX3DBackgroundNode
- Parameters:
newValue
- is new value for the transparency field.- Returns:
Background
- namely this same object to allow sequential method pipelining (i.e. consecutive method invocations on the same object).
-