public abstract class Eye extends Object implements Copyable
Camera
s and 2D
Window
s.
An Eye defines some intrinsic parameters (position()
, viewDirection()
, upVector()
...) and useful positioning tools that ease its placement (
showEntireScene()
, fitBall(Vec, float)
, lookAt(Vec)
...). It
exports its associated projection and view matrices and it can interactively be
modified using any interaction mechanism you can think of.
An Eye holds a collection of paths (keyFrameInterpolator(int key)
) each of
which can be interpolated ( playPath(int)
). It also provides visibility routines (
isPointVisible(Vec)
, ballVisibility(Vec, float)
,
boxVisibility(Vec, Vec)
), from which advanced geometry culling techniques can
be implemented.
The position()
and orientation()
of the Eye are defined by an
GenericFrame
(retrieved using frame()
). These
methods are just convenient wrappers to the equivalent Frame methods. This also means
that the Eye frame()
can be attached to a
Frame.referenceFrame()
which enables complex Eye
setups. An Eye has its own magnitude, different from that of the scene (i.e.,
Frame.magnitude()
doesn't necessarily equals 1
), which allows to scale the view. Use eyeCoordinatesOf(Vec)
and
worldCoordinatesOf(Vec)
(or any of the powerful Frame transformations, such as
Frame.coordinatesOf(Vec)
,
Frame.transformOf(Vec)
, ...) to convert to and from the
Eye frame()
coordinate system. projectedCoordinatesOf(Vec)
and
unprojectedCoordinatesOf(Vec)
will convert from screen to 3D coordinates.
An Eye can also be used outside of an Scene for its coordinate system conversion capabilities.
Modifier and Type | Class and Description |
---|---|
static class |
Eye.Visibility
Enumerates the different visibility states an object may have respect to the Eye
boundary.
|
Modifier and Type | Field and Description |
---|---|
boolean |
anchorFlag |
long |
lastNonFrameUpdate
Which was the last frame the Eye changes.
|
boolean |
pupFlag |
Vec |
pupVec |
Constructor and Description |
---|
Eye(AbstractScene scn) |
Modifier and Type | Method and Description |
---|---|
void |
addKeyFrameToPath(int key)
|
Vec |
anchor()
The point the Eye revolves around with the ROTATE action binding.
|
boolean |
anyInterpolationStarted()
Returns
true if any interpolation associated with this Eye is currently being
performed (and false otherwise). |
boolean |
areBoundaryEquationsEnabled()
Returns
true if automatic update of the eye boundary plane equations is
enabled and false otherwise. |
float |
aspectRatio()
Returns the Eye aspect ratio defined by
screenWidth() /
screenHeight() . |
abstract Vec |
at()
2D Windows return the postion.
|
abstract Eye.Visibility |
ballVisibility(Vec center,
float radius)
Returns
Eye.Visibility.VISIBLE ,
Eye.Visibility.INVISIBLE , or
Eye.Visibility.SEMIVISIBLE , depending whether the
sphere (of radius radius and center center ) is visible, invisible, or
semi-visible, respectively. |
abstract Eye.Visibility |
boxVisibility(Vec p1,
Vec p2)
Returns
Eye.Visibility.VISIBLE ,
Eye.Visibility.INVISIBLE , or
Eye.Visibility.SEMIVISIBLE , depending whether the
axis aligned box (defined by corners p1 and p2 ) is visible,
invisible, or semi-visible, respectively. |
void |
centerScene()
Moves the Eye so that its
sceneCenter() is projected on the center of the
window. |
abstract float[][] |
computeBoundaryEquations()
Convenience function that in 2D simply returns
computeFrustumPlanesCoefficients(new float [4][3]) and in 3D
computeFrustumPlanesCoefficients(new float [6][4]) . |
abstract float[][] |
computeBoundaryEquations(float[][] coef)
Fills
coef with the 6 plane equations of the camera frustum and returns it. |
abstract void |
computeProjection()
Computes the projection matrix associated with the Eye.
|
abstract void |
computeView()
Computes the View matrix associated with the Eye's
position() and
orientation() . |
void |
deletePath(int key)
Deletes the
keyFrameInterpolator(int) of index key . |
abstract float |
distanceToAnchor()
Returns the Eye
position() to anchor() distance in Scene units. |
float |
distanceToBoundary(int index,
Vec pos)
Returns the signed distance between point
pos and plane index in
Scene units. |
abstract float |
distanceToSceneCenter()
Returns the Eye
position() to sceneCenter() distance in Scene
units. |
void |
enableBoundaryEquations(boolean flag)
Enables or disables automatic update of the eye boundary plane equations every frame
according to
flag . |
Vec |
eyeCoordinatesOf(Vec src)
Returns the Eye frame coordinates of a point
src defined in world
coordinates. |
abstract void |
fitBall(Vec center,
float radius)
Moves the Eye so that the ball defined by
center and radius is
visible and fits the window. |
abstract void |
fitBoundingBox(Vec min,
Vec max)
Moves the Eye so that the (world axis aligned) bounding box (
min ,
max ) is entirely visible, using fitBall(Vec, float) . |
abstract void |
fitScreenRegion(Rect rectangle)
Moves the Eye so that the rectangular screen region defined by
rectangle
(pixel units, with origin in the upper left corner) fits the screen. |
void |
flip()
Same as
scene.flip() . |
float |
flySpeed()
Returns the fly speed of the Eye.
|
GenericFrame |
frame()
Returns the GrabberFrame attached to the Eye.
|
void |
fromView(Mat mv)
Convenience function that simply calls
fromView(mv, true) . |
abstract void |
fromView(Mat mv,
boolean recompute)
Sets the Eye
position() and orientation() from an OpenGL-like View
matrix. |
abstract Eye |
get()
Returns a deep copy of the object.
|
float[][] |
getBoundaryEquations()
Returns the boundary plane equations.
|
float[] |
getBoundaryWidthHeight()
Convenience function that simply returns
getOrthoWidthHeight(new
float[2]) . |
float[] |
getBoundaryWidthHeight(float[] target)
Fills in
target with the halfWidth and halfHeight of the Eye
boundary and returns it. |
float[] |
getOrthoWidthHeight() |
float[] |
getOrthoWidthHeight(float[] target) |
Mat |
getProjection()
Convenience function that simply returns
getProjectionMatrix(false) |
Mat |
getProjection(boolean recompute)
Convenience function that simply returns
getProjection(new Mat(), recompute) |
Mat |
getProjection(Mat m)
Convenience function that simply returns
getProjection(m, false) |
Mat |
getProjection(Mat m,
boolean recompute)
Fills
m with the Eye projection matrix values and returns it. |
Mat |
getView()
Convenience function that simply returns
getViewMatrix(false) |
Mat |
getView(boolean recompute)
Convenience function that simply returns
getViewMatrix(new Mat(), recompute) |
Mat |
getView(Mat m)
Convenience function that simply returns
getViewMatrix(m, false) |
Mat |
getView(Mat m,
boolean recompute)
Fills
m with the Eye View matrix values and returns it. |
int[] |
getViewport()
Convenience function that simply calls
return getViewport(int[]) . |
int[] |
getViewport(int[] vp)
Fills
viewport with the Eye viewport and returns it. |
void |
interpolateTo(GenericFrame fr)
Convenience function that simply calls
interpolateTo(fr, 1) . |
void |
interpolateTo(GenericFrame fr,
float duration)
Smoothly interpolates the Eye on a KeyFrameInterpolator path so that it goes to
fr . |
void |
interpolateToFitScene()
Interpolates the Eye on a one second KeyFrameInterpolator path so that the entire
scene fits the screen at the end.
|
void |
interpolateToZoomOnPixel(float x,
float y) |
abstract void |
interpolateToZoomOnPixel(Point pixel)
Makes the Eye smoothly zoom on the
Camera.pointUnderPixel(Point) pixel and
returns the world coordinates of the
Camera.pointUnderPixel(Point) . |
void |
interpolateToZoomOnRegion(Rect rectangle)
Smoothly moves the Eye so that the rectangular screen region defined by
rectangle (pixel units, with origin in the upper left corner) fits the
screen. |
abstract boolean |
isPointVisible(Vec point)
Returns
true if point is visible (i.e, lies within the Eye boundary)
and false otherwise. |
KeyFrameInterpolator |
keyFrameInterpolator(int key)
Returns the KeyFrameInterpolator that defines the Eye path number
key . |
KeyFrameInterpolator[] |
keyFrameInterpolatorArray()
Returns the eye
paths as an array. |
List<KeyFrameInterpolator> |
keyFrameInterpolatorList()
Returns the eye
paths as a list. |
HashMap<Integer,KeyFrameInterpolator> |
keyFrameInterpolatorMap()
Returns the eye
<id, KeyFrameInterpolator> map. |
long |
lastNonFrameUpdate() |
long |
lastUpdate()
Max between
GenericFrame.lastUpdate() and
lastNonFrameUpdate() . |
abstract void |
lookAt(Vec target)
2D Windows simply call
frame().setPosition(target.x(), target.y()) . |
Rotation |
orientation()
Returns the Eye orientation, defined in the world coordinate system.
|
float |
pixelToSceneRatio(Vec position)
Returns the pixel to scene (units) ratio at
position . |
void |
playPath(int key)
Makes the Eye follow the path of keyFrameInterpolator() number
key . |
Vec |
position()
Returns the Eye position, defined in the world coordinate system.
|
boolean |
project(float objx,
float objy,
float objz,
float[] windowCoordinate)
Similar to
gluProject : map object coordinates to window coordinates. |
boolean |
project(Mat projectionViewMat,
float objx,
float objy,
float objz,
float[] windowCoordinate) |
Vec |
projectedCoordinatesOf(Mat projview,
Vec src)
Convenience function that simply returns
projectedCoordinatesOf(projview, src, null) . |
Vec |
projectedCoordinatesOf(Mat projview,
Vec src,
Frame frame)
Returns the screen projected coordinates of a point
src defined in the
frame coordinate system. |
Vec |
projectedCoordinatesOf(Vec src)
Convenience function that simply returns
projectedCoordinatesOf(src, null) . |
Vec |
projectedCoordinatesOf(Vec src,
Frame frame)
Convenience function that simply returns
projectedCoordinatesOf(null, src, frame) . |
float |
rescalingOrthoFactor()
Simply returns
1 which is valid for 2d Windows. |
void |
resetPath(int key)
Resets the path of the
keyFrameInterpolator(int) number key . |
Vec |
rightVector()
Returns the normalized right vector of the Eye, defined in the world coordinate
system.
|
float |
rotationSensitivity()
Convenience wrapper function that simply returns
frame().rotationSensitivity() |
float |
scalingSensitivity()
Convenience wrapper function that simply returns
frame().scalingSensitivity() |
AbstractScene |
scene()
Returns the scene this object belongs to
|
Vec |
sceneCenter()
Returns the position of the scene center, defined in the world coordinate system.
|
float |
sceneRadius()
Returns the radius of the scene observed by the Eye in scene (world) units.
|
abstract float |
sceneToPixelRatio(Vec position)
Returns the ratio of scene (units) to pixel at
position . |
int |
screenHeight()
Returns the height (in pixels) of the Eye screen.
|
int |
screenWidth()
Returns the width (in pixels) of the Eye screen.
|
void |
setAnchor(Vec refP)
Sets the
anchor() , defined in the world coordinate system. |
boolean |
setAnchorFromPixel(float x,
float y) |
abstract boolean |
setAnchorFromPixel(Point pixel)
The
anchor() is set to the point located under pixel on screen. |
void |
setAspectRatio(float aspect)
Defines the Eye
aspectRatio() . |
void |
setFlySpeed(float speed)
Sets the Eye
flySpeed() . |
void |
setFrame(GenericFrame g)
Sets the Eye
frame() . |
void |
setKeyFrameInterpolator(int key,
KeyFrameInterpolator keyFInterpolator)
Sets the KeyFrameInterpolator that defines the Eye path of index
key . |
abstract void |
setOrientation(Rotation q)
Sets the Eye
orientation() , defined in the world coordinate system. |
void |
setPosition(Vec pos)
Sets the Eye
position() (the eye), defined in the world coordinate system. |
void |
setProjection(float[] source)
Convenience function that simply calls
setProjectionMatrix(source, false) . |
void |
setProjection(float[] source,
boolean transpose)
Fills the projection matrix with the
source matrix values (defined in
row-major order). |
void |
setProjection(Mat proj)
Fills the projection matrix with the
proj matrix values. |
void |
setRotationSensitivity(float sensitivity)
Convenience wrapper function that simply calls
frame().setRotationSensitivity(sensitivity) |
void |
setScalingSensitivity(float sensitivity)
Convenience wrapper function that simply calls
frame().setScalingSensitivity(sensitivity) |
abstract void |
setSceneBoundingBox(Vec min,
Vec max)
Similar to
setSceneRadius(float) and setSceneCenter(Vec) , but the
scene limits are defined by a (world axis aligned) bounding box. |
void |
setSceneCenter(Vec center)
Sets the
sceneCenter() . |
boolean |
setSceneCenterFromPixel(float x,
float y) |
abstract boolean |
setSceneCenterFromPixel(Point pixel)
The
sceneCenter() is set to the point located under pixel on screen. |
void |
setSceneRadius(float radius)
Sets the
sceneRadius() value in scene (world) units. |
void |
setScreenWidthAndHeight(int width,
int height)
Sets Eye
screenWidth() and screenHeight() (expressed in pixels). |
void |
setSpinningSensitivity(float sensitivity)
Convenience wrapper function that simply calls
frame().setSpinningSensitivity(sensitivity) |
void |
setTranslationSensitivity(float sensitivity)
Convenience wrapper function that simply calls
frame().setTranslationSensitivity(sensitivity) |
void |
setUpVector(Vec up)
Convenience function that simply calls
setUpVector(up, true) . |
abstract void |
setUpVector(Vec up,
boolean noMove)
Rotates the Eye so that its
upVector() becomes up (defined in the
world coordinate system). |
void |
showEntireScene()
Moves the Eye so that the entire scene is visible.
|
float |
spinningSensitivity()
Convenience wrapper function that simply returns
frame().spinningSensitivity() |
void |
stopInterpolations()
Stops all interpolations currently being performed associated with this Eye.
|
float |
translationSensitivity()
Convenience wrapper function that simply returns
frame().translationSensitivity() |
boolean |
unproject(float winx,
float winy,
float winz,
float[] objCoordinate) |
boolean |
unproject(Mat projectionViewInverseMat,
float winx,
float winy,
float winz,
float[] objCoordinate)
Similar to
gluUnProject : map window coordinates to object coordinates. |
Vec |
unprojectedCoordinatesOf(Mat projviewInv,
Vec src)
Convenience function that simply returns
unprojectedCoordinatesOf(projviewInv, src, null) . |
Vec |
unprojectedCoordinatesOf(Mat projviewInv,
Vec src,
Frame frame)
Returns the world unprojected coordinates of a point
src defined in the
screen coordinate system. |
Vec |
unprojectedCoordinatesOf(Vec src)
Convenience function that simply returns
unprojectedCoordinatesOf(src, null) . |
Vec |
unprojectedCoordinatesOf(Vec src,
Frame frame)
Convenience function that simply returns
unprojectedCoordinatesOf(null, src, frame) . |
void |
updateBoundaryEquations()
Updates the boundary plane equations according to the current eye setup, by simply
calling
computeBoundaryEquations() . |
Vec |
upVector()
Returns the normalized up vector of the Eye, defined in the world coordinate system.
|
Vec |
viewDirection()
Returns the normalized view direction of the Eye, defined in the world coordinate
system.
|
Vec |
worldCoordinatesOf(Vec src)
Returns the world coordinates of the point whose position
src is defined in
the Eye coordinate system. |
public long lastNonFrameUpdate
public boolean anchorFlag
public boolean pupFlag
public Vec pupVec
public Eye(AbstractScene scn)
public abstract Eye get()
Copyable
Typical implementation should simple look like: return new Object(this)
.
public GenericFrame frame()
This GrabberFrame defines its position()
, orientation()
and can
translate bogus events into Eye displacement. Set using
setFrame(GenericFrame)
.
public AbstractScene scene()
public abstract float distanceToSceneCenter()
position()
to sceneCenter()
distance in Scene
units.
3D Cameras return the projected Eye position()
to sceneCenter()
distance along the Camera Z axis and use it in
Camera.zNear()
and
Camera.zFar()
to optimize the Z range.
public abstract float distanceToAnchor()
position()
to anchor()
distance in Scene units.
3D Cameras return the projected Eye position()
to anchor()
distance
along the Camera Z axis and use it in getBoundaryWidthHeight(float[])
so
that when the Camera is translated forward then its frustum is narrowed, making the
object appear bigger on screen, as intuitively expected.
public Rotation orientation()
Actually returns frame().orientation()
. Use setOrientation(Rotation)
, setUpVector(Vec)
or lookAt(Vec)
to set the Eye orientation.
public long lastUpdate()
GenericFrame.lastUpdate()
and
lastNonFrameUpdate()
.lastNonFrameUpdate()
public long lastNonFrameUpdate()
lastUpdate()
public void flip()
scene.flip()
.AbstractScene.flip()
public final void setFrame(GenericFrame g)
frame()
.
If you want to move the Eye, use setPosition(Vec)
and
setOrientation(Rotation)
or one of the Eye positioning methods (
lookAt(Vec)
, fitBall(Vec, float)
, showEntireScene()
...)
instead.
This method is actually mainly useful if you derive the GrabberFrame class and want to use an instance of your new class to move the Eye.
A null
icf
reference will silently be ignored.
public abstract void lookAt(Vec target)
frame().setPosition(target.x(), target.y())
. 3D
Cameras set orientation()
, so that it looks at point target
defined
in the world coordinate system (The Camera position()
is not modified.
Simply Camera.setViewDirection(Vec)
).public final float spinningSensitivity()
frame().spinningSensitivity()
GenericFrame.spinningSensitivity()
public final void setSpinningSensitivity(float sensitivity)
frame().setSpinningSensitivity(sensitivity)
public final float rotationSensitivity()
frame().rotationSensitivity()
GenericFrame.rotationSensitivity()
public final void setRotationSensitivity(float sensitivity)
frame().setRotationSensitivity(sensitivity)
public final float translationSensitivity()
frame().translationSensitivity()
GenericFrame.translationSensitivity()
public final void setTranslationSensitivity(float sensitivity)
frame().setTranslationSensitivity(sensitivity)
public final float scalingSensitivity()
frame().scalingSensitivity()
GenericFrame.scalingSensitivity()
public final void setScalingSensitivity(float sensitivity)
frame().setScalingSensitivity(sensitivity)
public final Vec position()
Use setPosition(Vec)
to set the Eye position. Other convenient methods are
showEntireScene() or fitSphere(). Actually returns
Frame.position()
.
public void setPosition(Vec pos)
position()
(the eye), defined in the world coordinate system.public Vec upVector()
Set using setUpVector(Vec)
or setOrientation(Rotation)
. It is
orthogonal to viewDirection()
and to rightVector()
.
It corresponds to the Y axis of the associated frame()
(actually returns
frame().yAxis()
public void setUpVector(Vec up)
setUpVector(up, true)
.setUpVector(Vec, boolean)
public abstract void setUpVector(Vec up, boolean noMove)
upVector()
becomes up
(defined in the
world coordinate system).
The Eye is rotated around an axis orthogonal to up
and to the current
upVector()
direction.
Use this method in order to define the Eye horizontal plane.
When noMove
is set to false
, the orientation modification is
compensated by a translation, so that the anchor()
stays projected at the
same position on screen. This is especially useful when the Eye is an observer of the
scene (default action binding).
When noMove
is true, the Eye position()
is left unchanged, which is
an intuitive behavior when the Eye is in first person mode.
lookAt(Vec)
,
setOrientation(Rotation)
public Vec rightVector()
This vector lies in the Eye horizontal plane, directed along the X axis (orthogonal
to upVector()
and to viewDirection()
. Set using
setUpVector(Vec)
, lookAt(Vec)
or setOrientation(Rotation)
.
Simply returns frame().xAxis()
.
public abstract void setOrientation(Rotation q)
orientation()
, defined in the world coordinate system.public float sceneRadius()
In the case of a 3D Eye (a Camera) you need to provide such an approximation of the
scene dimensions so that the it can adapt its
Camera.zNear()
and
Camera.zFar()
values. See the sceneCenter()
documentation.
Note that AbstractScene.radius()
(resp.
AbstractScene.setRadius(float)
simply call this
method on its associated Eye.
setSceneBoundingBox(Vec, Vec)
public void setSceneRadius(float radius)
sceneRadius()
value in scene (world) units. Negative values are
ignored. It also sets flySpeed()
to 1% of sceneRadius()
Attention: 3d Camera also sets
Camera.focusDistance()
to
sceneRadius() / tan(fieldOfView()/2)
.
public abstract void setSceneBoundingBox(Vec min, Vec max)
setSceneRadius(float)
and setSceneCenter(Vec)
, but the
scene limits are defined by a (world axis aligned) bounding box.public float flySpeed()
Simply returns frame().flySpeed()
. See the
GenericFrame.flySpeed()
documentation. This value is
only meaningful when the action binding is MOVE_FORWARD or is MOVE_BACKWARD.
Set to 0.5% of the sceneRadius()
by setSceneRadius(float)
.
setFlySpeed(float)
public void setFlySpeed(float speed)
flySpeed()
.
Attention: This value is modified by setSceneRadius(float)
.
public abstract boolean setSceneCenterFromPixel(Point pixel)
sceneCenter()
is set to the point located under pixel
on screen.
2D windows always returns true.
3D Cameras returns true
if a point was found under pixel
and
false
if none was found (in this case no sceneCenter()
is set).
public boolean setSceneCenterFromPixel(float x, float y)
public Vec sceneCenter()
The scene observed by the Eye should be roughly centered on this position, and
included in a sceneRadius()
ball.
Default value is the world origin. Use setSceneCenter(Vec)
to change it.
setSceneBoundingBox(Vec, Vec)
,
Camera.zNear()
,
Camera.zFar()
public void setSceneCenter(Vec center)
sceneCenter()
.
Attention: This method also sets the anchor()
to
sceneCenter()
.
public Vec anchor()
Default value is the sceneCenter()
.
Attention: setSceneCenter(Vec)
changes this value.
public void setAnchor(Vec refP)
anchor()
, defined in the world coordinate system.public abstract boolean setAnchorFromPixel(Point pixel)
public boolean setAnchorFromPixel(float x, float y)
public float aspectRatio()
screenWidth()
/
screenHeight()
.
When the Eye is attached to a Scene, these values and hence the aspectRatio() are automatically fitted to the viewer's window aspect ratio using setScreenWidthAndHeight().
public void setAspectRatio(float aspect)
aspectRatio()
.
This value is actually inferred from the screenWidth()
/
screenHeight()
ratio. You should use
setScreenWidthAndHeight(int, int)
instead.
This method might however be convenient when the Eye is not associated with a Scene.
It actually sets the screenHeight()
to 100 and the screenWidth()
accordingly.
Camera.setFOVToFitScene()
public void setScreenWidthAndHeight(int width, int height)
screenWidth()
and screenHeight()
(expressed in pixels).
You should not call this method when the Eye is associated with a Scene, since the latter automatically updates these values when it is resized (hence overwriting your values).
Non-positive dimension are silently replaced by a 1 pixel value to ensure boundary coherence.
If your Eye is used without a Scene (offscreen rendering, shadow maps), use
setAspectRatio(float)
instead to define the projection matrix.
public final int screenWidth()
Set using setScreenWidthAndHeight(int, int)
. This value is automatically
fitted to the Scene's window dimensions when the Eye is attached to a Scene.
public final int screenHeight()
Set using setScreenWidthAndHeight(int, int)
. This value is automatically
fitted to the Scene's window dimensions when the Eye is attached to a Scene.
public Mat getProjection()
getProjectionMatrix(false)
getProjection(Mat, boolean)
public Mat getProjection(boolean recompute)
getProjection(new Mat(), recompute)
getProjection(Mat, boolean)
public Mat getProjection(Mat m)
getProjection(m, false)
getProjection(Mat, boolean)
public Mat getProjection(Mat m, boolean recompute)
m
with the Eye projection matrix values and returns it. If m
is
null
a new Mat will be created.
If recompute
is true
first calls computeProjection()
to
define the Eye projection matrix. Otherwise it returns the projection matrix
previously computed, e.g., as with
MatrixHelper.loadProjection()
.
public void setProjection(Mat proj)
proj
matrix values.public void setProjection(float[] source)
setProjectionMatrix(source, false)
.public void setProjection(float[] source, boolean transpose)
source
matrix values (defined in
row-major order).setProjection(Mat)
,
setProjection(float[])
public abstract void computeProjection()
If Eye is a 3D PERSPECTIVE Camera, defines a projection matrix using the
Camera.fieldOfView()
, aspectRatio()
,
Camera.zNear()
and
Camera.zFar()
parameters. If Eye is a 3D ORTHOGRAPHIC
Camera, the frustum's width and height are set using
getBoundaryWidthHeight()
. Both types use
Camera.zNear()
and
Camera.zFar()
to place clipping planes. These values
are determined from sceneRadius() and sceneCenter() so that they best fit the scene
size.
Use getProjection()
to retrieve this matrix.
Note: You must call this method if your Eye is not associated with a Scene and
is used for offscreen computations (using projectedCoordinatesOf()
for
instance).
setProjection(Mat)
public float[] getBoundaryWidthHeight()
getOrthoWidthHeight(new
float[2])
.getBoundaryWidthHeight(float[])
public float[] getBoundaryWidthHeight(float[] target)
target
with the halfWidth
and halfHeight
of the Eye
boundary and returns it. While target[0]
holds halfWidth
,
target[1]
holds halfHeight
. Values are computed as:
target[0] = rescalingOrthoFactor() * (frame().magnitude() * this.screenWidth() / 2)
and rescalingOrthoFactor() * (frame().magnitude() * this.screenHeight() / 2)
.
These values are valid for 2d Windows and ortho Cameras (but not persp) and they are expressed in virtual scene units.
In the case of ortho Cameras these values are proportional to the Camera (z
projected) distance to the anchor()
. When zooming on the object, the Camera
is translated forward and its boundary is narrowed, making the object appear bigger
on screen, as intuitively expected.
Overload this method to change this behavior if desired.
rescalingOrthoFactor()
public float[] getOrthoWidthHeight()
public float[] getOrthoWidthHeight(float[] target)
public float rescalingOrthoFactor()
1
which is valid for 2d Windows. Value is different for ortho
Cameras and thus the method is overridden by the camera class.getBoundaryWidthHeight(float[])
public Vec eyeCoordinatesOf(Vec src)
src
defined in world
coordinates.
worldCoordinatesOf(Vec)
performs the inverse transformation.
Note that the point coordinates are simply converted in a different coordinate
system. They are not projected on screen. Use
projectedCoordinatesOf(Vec, Frame)
for that.
public Vec worldCoordinatesOf(Vec src)
src
is defined in
the Eye coordinate system.
eyeCoordinatesOf(Vec)
performs the inverse transformation.
public abstract void computeView()
position()
and
orientation()
.
This matrix converts from the world coordinates system to the Eye coordinates system,
so that coordinates can then be projected on screen using the projection matrix (see
computeProjection()
).
Use getView()
to retrieve this matrix.
Note: You must call this method if your Eye is not associated with a Scene and
is used for offscreen computations (using projectedCoordinatesOf()
for
instance).
public Mat getView()
getViewMatrix(false)
public Mat getView(boolean recompute)
getViewMatrix(new Mat(), recompute)
public Mat getView(Mat m, boolean recompute)
m
with the Eye View matrix values and returns it. If m
is
null
a new Mat will be created.
If recompute
is true
first calls computeView()
to define the
Eye view matrix. Otherwise it returns the view matrix previously computed, e.g., as
with MatrixHelper.loadModelView()
.
public void fromView(Mat mv)
fromView(mv, true)
.fromView(Mat, boolean)
public abstract void fromView(Mat mv, boolean recompute)
position()
and orientation()
from an OpenGL-like View
matrix.
After this method has been called, getView()
returns a matrix equivalent to
mv
. Only the position()
and orientation()
of the Eye are
modified.
public final Vec projectedCoordinatesOf(Vec src)
projectedCoordinatesOf(src, null)
.projectedCoordinatesOf(Vec, Frame)
public final Vec projectedCoordinatesOf(Mat projview, Vec src)
projectedCoordinatesOf(projview, src, null)
.projectedCoordinatesOf(Vec, Frame)
public final Vec projectedCoordinatesOf(Vec src, Frame frame)
projectedCoordinatesOf(null, src, frame)
.projectedCoordinatesOf(Vec, Frame)
public final Vec projectedCoordinatesOf(Mat projview, Vec src, Frame frame)
src
defined in the
frame
coordinate system.
When frame
is null
, src
is expressed in the world coordinate
system. See projectedCoordinatesOf(Vec)
.
The x and y coordinates of the returned Vec are expressed in pixel, (0,0) being the
upper left corner of the window. The z coordinate ranges between 0.0 (near plane) and
1.0 (excluded, far plane). See the gluProject
man page for details.
Use AbstractScene.projectedCoordinatesOf(Vec)
which
is simpler and has been optimized by caching the Projection x View matrix.
Attention: This method only uses the intrinsic Eye parameters (see
getView()
, getProjection()
and getViewport()
) and is
completely independent of the processing matrices. You can hence define a virtual Eye
and use this method to compute projections out of a classical rendering context.
unprojectedCoordinatesOf(Vec, Frame)
public final Vec unprojectedCoordinatesOf(Vec src)
unprojectedCoordinatesOf(src, null)
.
public final Vec unprojectedCoordinatesOf(Mat projviewInv, Vec src)
unprojectedCoordinatesOf(projviewInv, src, null)
.
public final Vec unprojectedCoordinatesOf(Vec src, Frame frame)
unprojectedCoordinatesOf(null, src, frame)
.
public final Vec unprojectedCoordinatesOf(Mat projviewInv, Vec src, Frame frame)
src
defined in the
screen coordinate system.
The src.x
and src.y
input values are expressed in pixels, (0,0) being
the upper left corner of the window. The src.z
is a depth value ranging in
[0..1] (near and far plane respectively). In 3D Note that src.z
is not a
linear interpolation between Camera.zNear()
and
Camera.zFar()
;
src.z = zFar() / (zFar() - zNear()) * (1.0f - zNear() / z);
where z
is the distance from the point you project to the camera, along the
viewDirection()
. See the gluUnProject
man page for details.
The result is expressed in the frame
coordinate system. When frame
is
null
, the result is expressed in the world coordinates system. The possible
frame
hierarchy (i.e., when
Frame.referenceFrame()
is non-null) is taken into
account.
projectedCoordinatesOf(Vec, Frame)
performs the inverse transformation.
This method only uses the intrinsic Eye parameters (see getView()
,
getProjection()
and getViewport()
) and is completely independent of
the Processing matrices. You can hence define a virtual Eye and use this method to
compute un-projections out of a classical rendering context.
Attention: However, if your Eye is not attached to a Scene (used for offscreen
computations for instance), make sure the Eye matrices are updated before calling
this method (use computeView()
, computeProjection()
).
This method is not computationally optimized. If you call it several times with no change in the matrices, you should buffer the entire inverse projection matrix (view, projection and then viewport) to speed-up the queries. See the gluUnProject man page for details.
public int[] getViewport()
return
getViewport(int[])
.public int[] getViewport(int[] vp)
viewport
with the Eye viewport and returns it. If viewport is null (or
not the correct size), a new array will be created.
This method is mainly used in conjunction with
project(float, float, float, Mat, Mat, int[], float[])
, which requires such
a viewport. Returned values are (0, screenHeight()
, screenWidth()
,
- screenHeight()
), so that the origin is located in the upper left corner of
the window.
public boolean project(float objx, float objy, float objz, float[] windowCoordinate)
gluProject
: map object coordinates to window coordinates.objx
- Specify the object x coordinate.objy
- Specify the object y coordinate.objz
- Specify the object z coordinate.windowCoordinate
- Return the computed window coordinates.public boolean project(Mat projectionViewMat, float objx, float objy, float objz, float[] windowCoordinate)
public boolean unproject(float winx, float winy, float winz, float[] objCoordinate)
public boolean unproject(Mat projectionViewInverseMat, float winx, float winy, float winz, float[] objCoordinate)
gluUnProject
: map window coordinates to object coordinates.projectionViewInverseMat
- Specify the cached (projection * modelvview)^1 matrix.winx
- Specify the window x coordinate.winy
- Specify the window y coordinate.winz
- Specify the window z coordinate.objCoordinate
- Return the computed object coordinates.public HashMap<Integer,KeyFrameInterpolator> keyFrameInterpolatorMap()
<id, KeyFrameInterpolator>
map.public KeyFrameInterpolator[] keyFrameInterpolatorArray()
paths
as an array.public List<KeyFrameInterpolator> keyFrameInterpolatorList()
paths
as a list.public KeyFrameInterpolator keyFrameInterpolator(int key)
key
.
The returned KeyFrameInterpolator may be null (if no path is defined for key
key
).
public void setKeyFrameInterpolator(int key, KeyFrameInterpolator keyFInterpolator)
key
.public void addKeyFrameToPath(int key)
position()
and orientation()
as a keyFrame to
path key
.
This method can also be used if you simply want to save an Eye point of view (a path
made of a single keyFrame). Use playPath(int)
to make the Eye play the
keyFrame path (resp. restore the point of view). Use deletePath(int)
to
clear the path.
The default keyboard shortcuts for this method are keys [1-5].
If you use directly this method and the keyFrameInterpolator(int)
does not
exist, a new one is created.
public void playPath(int key)
key
.
If the interpolation is started, it stops it instead.
This method silently ignores undefined (empty) paths (see keyFrameInterpolator()).
The default keyboard shortcuts for this method are keys [1-5].
public void deletePath(int key)
keyFrameInterpolator(int)
of index key
.public void resetPath(int key)
keyFrameInterpolator(int)
number key
.
If this path is not being played (see playPath(int)
and
KeyFrameInterpolator.interpolationStarted()
), resets
it to its starting position (see
KeyFrameInterpolator.resetInterpolation()
). If the
path is played, simply stops interpolation.
public boolean anyInterpolationStarted()
true
if any interpolation associated with this Eye is currently being
performed (and false
otherwise).public void stopInterpolations()
public abstract float[][] computeBoundaryEquations()
computeFrustumPlanesCoefficients(new float [4][3])
and in 3D
computeFrustumPlanesCoefficients(new float [6][4])
.
Attention: You should not call this method explicitly, unless you need the
frustum equations to be updated only occasionally (rare). Use
AbstractScene.enableBoundaryEquations()
which
automatically update the frustum equations every frame instead.
computeBoundaryEquations(float[][])
public abstract float[][] computeBoundaryEquations(float[][] coef)
coef
with the 6 plane equations of the camera frustum and returns it.
In 2D the four 4-component vectors of coef
respectively correspond to the
left, right, top and bottom Window boundary lines. Each vector holds a plane equation
of the form:
a*x + b*y + c = 0
where a
, b
and c
are the 3
components of each vector, in that order.
In 3D the six 4-component vectors of coef
respectively correspond to the
left, right, near, far, top and bottom Camera frustum planes. Each vector holds a
plane equation of the form:
a*x + b*y + c*z + d = 0
where a
, b
, c
and d
are the 4 components of each
vector, in that order.
This format is compatible with the gl.glClipPlane()
function. One camera
frustum plane can hence be applied in an other viewer to visualize the culling
results:
// Retrieve place equations
float [][] coef =
mainViewer.camera().getFrustumPlanesCoefficients();
// These two additional clipping planes (which must have been enabled)
// will reproduce the mainViewer's near and far clipping.
gl.glClipPlane(GL.GL_CLIP_PLANE0, coef[2]);
gl.glClipPlane(GL.GL_CLIP_PLANE1, coef[3]);
Attention: You should not call this method explicitly, unless you need the
frustum equations to be updated only occasionally (rare). Use
AbstractScene.enableBoundaryEquations()
which
automatically update the frustum equations every frame instead.
computeBoundaryEquations()
public void enableBoundaryEquations(boolean flag)
flag
. Computation of the equations is expensive and hence is
disabled by default.updateBoundaryEquations()
public boolean areBoundaryEquationsEnabled()
true
if automatic update of the eye boundary plane equations is
enabled and false
otherwise. Computation of the equations is expensive and
hence is disabled by default.updateBoundaryEquations()
public void updateBoundaryEquations()
computeBoundaryEquations()
.
Attention: You should not call this method explicitly, unless you need the
boundary equations to be updated only occasionally (rare). Use
AbstractScene.enableBoundaryEquations()
which
automatically update the boundary equations every frame instead.
public float[][] getBoundaryEquations()
The six 4-component vectors returned by this method, respectively correspond to the left, right, near, far, top and bottom Eye boundary planes. Each vector holds a plane equation of the form:
a*x + b*y + c*z + d = 0
where a
, b
, c
and d
are the 4 components of each
vector, in that order.
Attention: The eye boundary plane equations should be updated before calling
this method. You may compute them explicitly (by calling
computeBoundaryEquations()
) or enable them to be automatic updated in your
Scene setup (with
AbstractScene.enableBoundaryEquations()
).
public float distanceToBoundary(int index, Vec pos)
pos
and plane index
in
Scene units. The distance is negative if the point lies in the planes's boundary
halfspace, and positive otherwise.
index
is a value between 0
and 5
which respectively
correspond to the left, right, near, far, top and bottom Eye boundary planes.
Attention: The eye boundary plane equations should be updated before calling
this method. You may compute them explicitly (by calling
computeBoundaryEquations()
) or enable them to be automatic updated in your
Scene setup (with
AbstractScene.enableBoundaryEquations()
).
public abstract boolean isPointVisible(Vec point)
true
if point
is visible (i.e, lies within the Eye boundary)
and false
otherwise.
Attention: The Eye boundary plane equations should be updated before calling
this method. You may compute them explicitly (by calling
computeBoundaryEquations()
) or enable them to be automatic updated in your
Scene setup (with
AbstractScene.enableBoundaryEquations()
).
public abstract Eye.Visibility ballVisibility(Vec center, float radius)
Eye.Visibility.VISIBLE
,
Eye.Visibility.INVISIBLE
, or
Eye.Visibility.SEMIVISIBLE
, depending whether the
sphere (of radius radius
and center center
) is visible, invisible, or
semi-visible, respectively.
Attention: The Eye boundary plane equations should be updated before calling
this method. You may compute them explicitly (by calling
computeBoundaryEquations()
) or enable them to be automatic updated in your
Scene setup (with
AbstractScene.enableBoundaryEquations()
).
public abstract Eye.Visibility boxVisibility(Vec p1, Vec p2)
Eye.Visibility.VISIBLE
,
Eye.Visibility.INVISIBLE
, or
Eye.Visibility.SEMIVISIBLE
, depending whether the
axis aligned box (defined by corners p1
and p2
) is visible,
invisible, or semi-visible, respectively.
Attention: The Eye boundary plane equations should be updated before calling
this method. You may compute them explicitly (by calling
computeBoundaryEquations()
) or enable them to be automatic updated in your
Scene setup (with
AbstractScene.enableBoundaryEquations()
).
public abstract float sceneToPixelRatio(Vec position)
position
.
A line of n * sceneToPixelRatio()
scene units, located at position
in
the world coordinates system, will be projected with a length of n
pixels on
screen.
Use this method to scale objects so that they have a constant pixel size on screen.
The following code will draw a 20 pixel line, starting at sceneCenter()
and
always directed along the screen vertical direction:
beginShape(LINES);
vertex(sceneCenter().x, sceneCenter().y, sceneCenter().z);
Vec v = Vec.add(sceneCenter(), Vec.mult(upVector(), 20 * sceneToPixelRatio(sceneCenter())));
vertex(v.x, v.y, v.z);
endShape();
public float pixelToSceneRatio(Vec position)
position
.
Convenience function that simply returns 1 / sceneToPixelRatio(position)
.
sceneToPixelRatio(Vec)
public void interpolateToZoomOnRegion(Rect rectangle)
rectangle
(pixel units, with origin in the upper left corner) fits the
screen.
The Eye is translated (its orientation()
is unchanged) so that
rectangle
is entirely visible. Since the pixel coordinates only define a
boundary in 3D, it's the intersection of this boundary with a plane
(orthogonal to the viewDirection()
and passing through the
sceneCenter()
) that is used to define the 3D rectangle that is eventually
fitted.
fitScreenRegion(Rect)
public void interpolateToFitScene()
The scene is defined by its sceneCenter()
and its sceneRadius()
.
See showEntireScene()
.
The orientation()
of the Eye is not modified.
interpolateToZoomOnPixel(Point)
public void interpolateTo(GenericFrame fr)
interpolateTo(fr, 1)
.interpolateTo(GenericFrame, float)
public void interpolateTo(GenericFrame fr, float duration)
fr
.
fr
is expressed in world coordinates. duration
tunes the
interpolation speed.
public abstract void fitBall(Vec center, float radius)
center
and radius
is
visible and fits the window.
In 3D the Camera is simply translated along its viewDirection()
so that the
sphere fits the screen. Its orientation()
and its
Camera.fieldOfView()
are unchanged. You should
therefore orientate the Camera before you call this method.
public abstract void fitBoundingBox(Vec min, Vec max)
min
,
max
) is entirely visible, using fitBall(Vec, float)
.public abstract void fitScreenRegion(Rect rectangle)
rectangle
(pixel units, with origin in the upper left corner) fits the screen.
in 3D the Camera is translated (its orientation()
is unchanged) so that
rectangle
is entirely visible. Since the pixel coordinates only define a
frustum in 3D, it's the intersection of this frustum with a plane (orthogonal
to the viewDirection()
and passing through the sceneCenter()
) that
is used to define the 3D rectangle that is eventually fitted.
public void showEntireScene()
Simply calls fitBall(Vec, float)
on a sphere defined by
sceneCenter()
and sceneRadius()
.
You will typically use this method at init time after you defined a new
sceneRadius()
.
public void centerScene()
sceneCenter()
is projected on the center of the
window. The orientation()
(and in the case of perps 3d
Camera.fieldOfView()
) is (are) unchanged.
Simply projects the current position on a line passing through sceneCenter()
.
showEntireScene()
public Vec viewDirection()
frame()
(
frame().inverseTransformOf(new Vec(0.0f, 0.0f, -1.0f))
) whih in 2D always is
(0,0,-1)
In 3D change this value using
Camera.setViewDirection(Vec)
, lookAt(Vec)
or
setOrientation(Rotation)
. It is orthogonal to upVector()
and to
rightVector()
.
public abstract Vec at()
viewDirection()
). Useful for setting the Processing camera() which uses a
similar approach of that found in gluLookAt.lookAt(Vec)
public abstract void interpolateToZoomOnPixel(Point pixel)
Camera.pointUnderPixel(Point)
pixel
and
returns the world coordinates of the
Camera.pointUnderPixel(Point)
.
In 3D nothing happens if no
Camera.pointUnderPixel(Point)
is found. Otherwise a
KeyFrameInterpolator is created that animates the Camera on a one second path that
brings the Camera closer to the point under pixel
.
interpolateToFitScene()
public void interpolateToZoomOnPixel(float x, float y)
Processing Library proscene by Jean Pierre Charalambos. (c) 2014-2017 National University of Colombia