SBVIEWVOLUME(3iv)

📦 version 2.1.6.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 SbViewVolume — the 3D viewing volume class 💖

okay so bestie, you opened the SbViewVolume(3IV) page and honestly? you ate. this is the whole vibe: a class that represents a 3D viewing volume, aka frusta and picking volumes. let's get into it, no skimming, every single detail stays. 🫶

🌈 INHERITS FROM 🌈

SbViewVolume

(yes she inherits from herself. main character energy, we love that for her 💅)

✨ SYNOPSIS ✨

#include <Inventor/SbLinear.h>

enum ProjectionType {
     SbViewVolume::ORTHOGRAPHIC  Orthographic projection
     SbViewVolume::PERSPECTIVE   Perspective projection
}

     Methods from class SbViewVolume:

                    SbViewVolume()
                    ~SbViewVolume()
void                getMatrices(SbMatrix &affine, SbMatrix &proj) const
SbMatrix            getMatrix() const
SbMatrix            getCameraSpaceMatrix() const
void                projectPointToLine(const SbVec2f &pt, SbLine &line)
                         const
void                projectPointToLine(const SbVec2f &pt, SbVec3f &line0,
                         SbVec3f &line1) const
void                projectToScreen(const SbVec3f &src, SbVec3f &dst)
                         const
SbPlane             getPlane(float distFromEye) const
SbVec3f             getSightPoint(float distFromEye) const
SbVec3f             getPlanePoint(float distFromEye, const SbVec2f
                         &normPoint) const
SbRotation          getAlignRotation(SbBool rightAngleOnly = FALSE) const
float               getWorldToScreenScale(const SbVec3f &worldCenter,
                         float normRadius) const
SbVec2f             projectBox(const SbBox3f &box) const
SbViewVolume        narrow(float left, float bottom, float right, float
                         top) const
SbViewVolume        narrow(const SbBox3f &box) const
void                ortho(float left, float right, float bottom, float
                         top, float near, float far)
void                perspective(float fovy, float aspect, float near,
                         float far)
void                rotateCamera(const SbRotation &q)
void                translateCamera(const SbVec3f &v)
SbVec3f             zVector() const
SbViewVolume        zNarrow(float near, float far) const
void                scale(float factor)
void                scaleWidth(float ratio)
void                scaleHeight(float ratio)
ProjectionType      getProjectionType() const
const SbVec3f &     getProjectionPoint() const
const SbVec3f &     getProjectionDirection() const
float               getNearDist() const
float               getWidth() const
float               getHeight() const
float               getDepth() const

🦋 DESCRIPTION 🦋

so this class is literally the class used to represent a 3D viewing volume. that's the whole job. it represents viewing frusta and picking volumes — the stuff your camera sees and the stuff your mouse can grab. 🔥

for perspective projection, the view volume is a frustum (yes, the pointy one, iconic shape tbh). for orthographic (parallel) projection, the view volume is a rectangular prism. two completely different silhouettes, same class. versatility queen. 👑

💅 METHODS 💅

🌸 SbViewVolume(), ~SbViewVolume()

constructor and destructor. the hello and the bye. the entrance and the exit. 🎀

🌸 void getMatrices(SbMatrix &affine, SbMatrix &proj) const

hands you back two matrices that correspond to the view volume.

  • the first one is a viewing matrix, and it's guaranteed to be an affine transformation (promise, no cap).
  • the second one is suitable for use as a projection matrix in OpenGL.

two matrices, one call, we love efficiency. ✨

🌸 SbMatrix getMatrix() const

same energy as the method above, except it returns the affine and projection parts together in one single matrix, i.e. affine.multRight( proj ). one matrix instead of two, lowkey convenient. 💜

🌸 SbMatrix getCameraSpaceMatrix() const

returns a matrix that transforms the view volume into camera space. what does that even mean? it:

  • translates the view volume so the viewpoint sits at the origin 🎯
  • rotates it so the view direction is along the negative z axis

that's the whole transformation. camera space glow-up. 🌟

🌸 void projectPointToLine(const SbVec2f &pt, SbLine &line) const

🌸 void projectPointToLine(const SbVec2f &pt, SbVec3f &line0, SbVec3f &line1) const

maps a 2D point to a 3D line. the 2D point lives in the range 0 <= x,y <= 1. that's it, that's the mapping. 🧚

🌸 void projectToScreen(const SbVec3f &src, SbVec3f &dst) const

maps the 3D point in world coordinates to a 2D point in normalized screen coordinates, where 0 <= x,y,z <= 1.

and now the important part, bestie, don't skip this: the z-screen coordinate represents the homogenized z coordinate, which goes — and this is nonlinearly, so don't come for me — from 0 at the near clipping plane to 1 at the far clipping plane. 📐

🌸 SbPlane getPlane(float distFromEye) const

returns a plane parallel to the near (or far) plane of the view volume, sitting at a given distance from the projection point (the eye). parallel bestie, never intersecting. 🪞

🌸 SbVec3f getSightPoint(float distFromEye) const

returns the point along the line of sight at the given distance from the projection point (eye). the sight line, the gaze, the look. 👀

🌸 SbVec3f getPlanePoint(float distFromEye, const SbVec2f &normPoint) const

returns the projection of a given point in normalized screen coordinates (peep projectToScreen()) onto the plane parallel to the near plane that is distFromEye units from the eye. yes, that sentence is a mouthful, yes it's correct. 💫

🌸 SbRotation getAlignRotation(SbBool rightAngleOnly = FALSE) const

returns a rotation that would align a viewed object so that:

  • its positive x-axis (of its object space) is to the right in the view ➡️
  • its positive y-axis is up ⬆️

if rightAngleOnly is TRUE, it'll come as close as it can to this goal by using only 90 degree rotations. snapping to the grid, basically. the default is FALSE. 🔲

🌸 float getWorldToScreenScale(const SbVec3f &worldCenter, float normRadius) const

returns a scale factor that would scale a unit sphere centered at worldCenter so that it would appear to have the given radius in normalized screen coordinates when projected onto the near plane. unit sphere → screen-sized diva. 🍓

🌸 SbVec2f projectBox(const SbBox3f &box) const

projects the given 3D bounding box onto the near plane and returns the size (in normalized screen coordinates) of the rectangular region that encloses it. box goes in, rectangle size comes out. 📦

🌸 SbViewVolume narrow(float left, float bottom, float right, float top) const

given a view volume, narrows the view to the given sub-rectangle of the near plane. the coordinates of the rectangle are between 0 and 1, where:

  • (0,0) is the lower-left corner of the near plane
  • (1,1) is the upper-right corner

zooming in with receipts. 🔍

🌸 SbViewVolume narrow(const SbBox3f &box) const

narrows a view volume by the given box. heads up: the box must lie inside the unit cube, and the view will be shrunk according to the size of the box. 🎁

🌸 void ortho(float left, float right, float bottom, float top, float near, float far)

sets up an orthographic view volume with the given sides. the parameters are the same as for the OpenGL glOrtho() routine. classic. 🏛️

🌸 void perspective(float fovy, float aspect, float near, float far)

sets up a perspective view volume with the given field of view and aspect ratio. the parameters are the same as for the OpenGL gluPerspective() routine, except that the field of view angle is specified in radians. 📐 (radians, bestie, not degrees. i said what i said.)

🌸 void rotateCamera(const SbRotation &q)

rotate the camera view direction. and here's the note that matters: this accomplishes the reverse of doing an OpenGL glRotate() command after defining a camera — that one rotates the scene viewed by the camera. this one rotates the camera. opposite directions, same energy. 🔄

🌸 void translateCamera(const SbVec3f &v)

translate the camera viewpoint. and same deal as above: this accomplishes the reverse of doing an OpenGL glTranslate() command after defining a camera, which translates the scene viewed by the camera. camera moves vs. world moves, pick your fighter. 🚶‍♀️

🌸 SbVec3f zVector() const

returns the positive z axis in eye space. and in this coordinate system, the z value of the near plane should be GREATER than the z value of the far plane. yes, greater. this is not a typo, do not "fix" it, it's just how eye space works here. 💀

🌸 SbViewVolume zNarrow(float near, float far) const

returns a narrowed view volume which contains as tightly as possible the given interval on the z axis (in eye space). one caveat: the returned view volume will never be larger than the current volume.

near and far are given in terms of zVector(), which means near > far must hold. yes, again, greater-than. ⚠️

🌸 void scale(float factor)

scales width and height of view volume by the given factor. simple, clean, proportional. ✨

🌸 void scaleWidth(float ratio)

🌸 void scaleHeight(float ratio)

scales the view volume to be the given ratio of its current width or height, leaving the resulting view volume centered about the same point (in the near plane) as the current one. stretched but still centered, balanced queen. ⚖️

🌸 ProjectionType getProjectionType() const

🌸 const SbVec3f & getProjectionPoint() const

🌸 const SbVec3f & getProjectionDirection() const

returns projection information. that's the whole description, bestie, no notes. 📋

🌸 float getNearDist() const

returns distance from projection point to near plane. just the one number. 🎯

🌸 float getWidth() const

🌸 float getHeight() const

🌸 float getDepth() const

returns bounds of viewing frustum. width, height, depth — the full three-dimensional measurement moment. 📏

👀 SEE ALSO 👀

SbVec3f, SbVec2f, SbBox3f, SbMatrix, SbRotation

(the whole friend group, honestly. go say hi to them too.) 🫶

okay bestie that's the entire page, nothing skipped, nothing ghosted. 💖 this was SbViewVolume(3IV) — page from the SbViewVolume(3IV)() footer, and no date on that footer so we're just gonna say it's timeless, periodt. go project something iconic. 🌈✨🎀

📦 where this page comes from