GUI_ViewParameter.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        GUI_ViewParameter (Geometry Render Library, C++)
 *
 * COMMENTS:
 *              ViewParameter contains information relating to the
 *              viewport's physical characteristics, eg aspect ratio,
 *              position, lookat.
 *
 */

#ifndef __GUI_ViewParameter__
#define __GUI_ViewParameter__

#include "GUI_API.h"
#include <UT/UT_BoundingBox.h>
#include <UT/UT_Matrix3.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_Quaternion.h>
#include <UT/UT_Rect.h>
#include <UT/UT_Vector3.h>
#include <UT/UT_VectorTypes.h>
#include <UT/UT_Plane.h>

#include <RE/RE_RenderContext.h>

typedef void    (*GUI_TransformCallback)(UT_DMatrix4 &, fpreal time, void *);
typedef void    (*GUI_HomeRotCallback)(UT_Matrix3R &, void *);

class GUI_API GUI_ViewFlag
{
public:
                 GUI_ViewFlag()
                 {
                    ortho               = 0;
                    applyAspect         = 0;
                    matrixDirty         = 1;
                    iMatrixDirty        = 1;
                    boxZoom             = 0;
                    viewportDirty       = 0;
                    rotoTrackWindow     = 1;
                    initXform           = 0;
                    rxyzDirty           = 1;
                 }

    // ASCII methods to save and load flags
    void         save(std::ostream &os) const;
    bool         load(UT_IStream &is);

    unsigned     ortho:1,
                 applyAspect:1,
                 matrixDirty:1,
                 iMatrixDirty:1,
                 boxZoom:1,
                 viewportDirty:1,
                 rotoTrackWindow:1,
                 initXform:1,
                 rxyzDirty:1;
};

class GUI_API GUI_ViewParameter
{
public:
                 GUI_ViewParameter();
                ~GUI_ViewParameter();

                 GUI_ViewParameter(const GUI_ViewParameter &) = delete;
    enum         axis { OBLIQUE, CUSTOM, XAXIS, YAXIS, ZAXIS,
                            FRONT, RIGHT, TOP, BACK, LEFT, BOTTOM, CPLANE };

    enum         orientation { Y_UP, Z_UP };

    void         getViewport(UT_DimRect &area) const
                 {
                     int w,h;
                     getViewportSize(w,h);
                     area.set(myViewportLeft, myViewportBottom, w,h);
                 }
    void         getViewport(int &l, int &r, int &b, int &t) const;
    void         getViewportSize(int &w, int &h) const
                 {
                     // Note that we have inclusive coordinates.
                     w = myViewportRight - myViewportLeft + 1;
                     h = myViewportTop - myViewportBottom + 1;
                 }
    int          getViewportWidth() const
                    { return myViewportRight - myViewportLeft + 1; }
    int          getViewportHeight() const
                    { return myViewportTop - myViewportBottom + 1; }
    void         setViewport(RE_RenderContext r, int x, int y, int w, int h);
    void         setViewport(RE_RenderContext r, const UT_DimRect &viewarea)
                    { setViewport(r, viewarea.x(), viewarea.y(),
                                     viewarea.w(), viewarea.h()); }

    // Utility for converting our viewport into a UT_Rect.
    UT_InclusiveRect getViewport() const
                { return UT_InclusiveRect(myViewportLeft, myViewportBottom,
                                          myViewportRight, myViewportTop); }


    // Both setViewport and setView must be called before setProjection.
    // r may be NULL to set the projection matrix without loading it into
    // RE_Render.
    void         setProjection(RE_RenderContext r);

    // Returns the projection matrix. If depth_adjust is false, Z is not
    // mapped to [0,1], and instead remains as-is.
    void         getProjection(UT_Matrix4D &proj, bool depth_adjust=true);

    // Returns a projection matrix with near at 1.0 and far at 0.0 mapped to
    // [0,1]. If `infinite_far_plane` is true, assume an infinitely far clip and
    // ignore the far plane defined in this object.
    void         getReverseDepthProjection(UT_Matrix4D &proj,
                                           bool infinite_far_plane);

    void         getUnclippedProjection(UT_Matrix4D &project,
                                        fpreal left_crop = 0.0,
                                        fpreal right_crop = 1.0,
                                        fpreal bottom_crop = 0.0,
                                        fpreal top_crop = 1.0);

    // temporarily use this projection matrix. This class does not take
    // ownership.
    void         setProjectionOverride(UT_Matrix4D *override);

    // Get the direction a particular point (px, py) in the camera's
    // near plane is pointing to in world coordinates. The range of
    // (px, py) is (0, 0) to (1, 1) with (0, 0) representing the 
    // lower-left corner and the default arguments represent the center of
    // the screen.
    UT_Vector3   getCameraDir(fpreal px = 0.5, fpreal py = 0.5);

    // A utility method to return the world space plane representing our
    // view plane.  The point will be set to the center of the view and
    // the normal will point towards the camera.
    UT_PlaneD    getViewPlane();

    // The view is a subregion of the viewport that represents the current
    // "camera" view.  Aspect ratio bars are used to dim the parts of the
    // viewport not in this view.  The window coordinates are relative to
    // this view, not the viewport.
    void         setView(const UT_DimRect &area)
                    { setView(area.x(), area.y(), area.w(), area.h()); }
    void         setView(int x, int y, int w, int h);
    void         getView(int &l, int &r, int &b, int &t) const;
    int          getViewWidth() const
                    { return myViewRight - myViewLeft + 1; }
    int          getViewHeight() const
                    { return myViewTop - myViewBottom + 1; }
    // Utility for converting our viewport into a UT_Rect.
    UT_InclusiveRect getView() const
                { return UT_InclusiveRect(myViewLeft, myViewBottom,
                                          myViewRight, myViewTop); }

    // A handy method to compute projection bounds for the viewport such
    // that the specified bounds map to the view subregion.
    void         viewToViewportProjectionBounds(
                    fpreal &left, fpreal &right,
                    fpreal &bottom, fpreal &top) const;

    // Convenience methods to query the margins on each side of the view
    // subregion.
    int          getLeftMargin() const
                    { return myViewLeft - myViewportLeft; }
    int          getRightMargin() const
                    { return myViewportRight - myViewRight; }
    int          getBottomMargin() const
                    { return myViewBottom - myViewportBottom; }
    int          getTopMargin() const
                    { return myViewportTop - myViewTop; }

    void         homeToBox(int width, int height, fpreal minzoom, 
                           UT_BoundingBox &box, const UT_Matrix3R *rot = NULL,
                           bool centre_to_origin = false, bool zoom_in = false);
    void         homeRotation(axis a, UT_Matrix3R &rot) const;
    void         homeRotation(axis a);

    void         resetFOV();

    // Set the default camera FOV, 0-180 degrees.
    void         setDefaultFOV(fpreal fov_in_degrees);
    fpreal       getDefaultFOV() const { return myView.myDefaultFOV; }

    // Query the rotation that converts the view rotation from the old mode
    // to the new mode.
    static void  getOrientationChangeRotation(
                                    GUI_ViewParameter::orientation old_mode,
                                    GUI_ViewParameter::orientation new_mode,
                                    UT_Matrix3R &rot);

    // Convert a view transform relative to the old_mode to the corresponding
    // view transform relative to the new mode.
    void         convertTransform(GUI_ViewParameter::axis home_axis,
                                  GUI_ViewParameter::orientation old_mode,
                                  GUI_ViewParameter::orientation new_mode);

    // To perform view operations that are being exported continuously, we
    // need to cache some data to account for view changes that occur as a
    // result of the exporting.  Generally, you'll want to call the begin
    // method on a UI_VALUE_START and the end method on a UI_VALUE_CHANGED.
    void         beginContinuouslyExportedOperation();
    void         endContinuouslyExportedOperation();
    bool         continuouslyExportedOperationInProgress() const;

    void         rotate(UT_Axis3::axis axis, fpreal dx);
    void         rotate(const UT_Vector3R &axis, fpreal dx);
    void         rotate(const UT_Quaternion &quat);
    void         trackball(fpreal dx, fpreal dy);
    void         incrementtrackball(fpreal dx, fpreal dy, int finish);
    void         eulertumble(fpreal dx, fpreal dy, int finish, bool lock);
    void         dotumble(fpreal dx, fpreal dy, int finish);

    void         scroll(fpreal dx, fpreal dy);
    // Scroll using the specified viewport size instead of our settings.  Used
    // for scrolling linked ortho viewports.
    void         scroll(fpreal dx, fpreal dy, const UT_InclusiveRect &viewport);
    // Scroll to maintain the specified world position under the cursor.  This
    // method is unnecessary when using an orthographic projection.
    void         worldLockedScroll(const UT_Vector3R &locked_pos,
                                   fpreal dx, fpreal dy);

    void         dolly(fpreal dx,
                       bool precise_zoom = false,
                       bool smooth_deltas = false);

    // Dolly using a specified world-space direction (instead of towards the
    // center of the view as in a regular dolly).  The use of world space is
    // a convenience for the GUI_ViewState wrapper that would otherwise have
    // to transform this to a view space direction for each instance of this
    // class.
    void         directedDolly(const UT_Vector3R &unit_worldspace_dir,
                               fpreal dx, bool precise_zoom = false,
                               bool smooth_deltas = false);

    enum GUI_ZoomItem
    {
        GUI_WIN_SIZE,
        GUI_ORTHO_WIDTH
    };
    void         zoom(fpreal dx, GUI_ZoomItem item, bool precise_zoom = false);
    // Zoom using the specified viewport size instead of our settings.  Used
    // for zooming linked ortho viewports.
    void         zoom(fpreal dx, GUI_ZoomItem item,
                      const UT_InclusiveRect &viewport,
                      bool precise_zoom = false);

    // Versions of the zoom() methods that center the zoom around the given
    // (normalized) screen position (sx, sy).  This affects either the window
    // offset, when GUI_WIN_SIZE is specified, or the view position, when
    // GUI_ORTHO_WIDTH is specified.
    void         offsetZoom(fpreal sx, fpreal sy, fpreal dx, GUI_ZoomItem item,
                            bool precise_zoom = false);
    void         offsetZoom(fpreal sx, fpreal sy, fpreal dx, GUI_ZoomItem item,
                            const UT_InclusiveRect &viewport,
                            bool precise_zoom = false);

    // Dolly onto a target located at a specified distance.
    // Note that the location and size of the "box" must be
    // normalized to [0, 1]
    // ** Note : Aspect ratio of the box is assumed to match aspect ratio 
    //           of the viewport!
    void         boxZoom(fpreal firstx, fpreal firsty, fpreal lastx, 
                         fpreal lasty, fpreal distance);

    void         screenScroll(fpreal dx, fpreal dy);

    // Returns the width of the frustum cross-section at the distance t.
    static fpreal getFrustumWidth(fpreal t, fpreal aperture, fpreal focal_length,
                                  fpreal orthowidth, bool is_ortho);

    // Returns the centre of the frustum (cx, cy) and the half-width and
    // half-height (hw, hh), from these, you can compute the corners of the
    // frustum.
    static void  getFrustumCenter(fpreal frustum_width, fpreal aspect,
                                   fpreal x_offset, fpreal y_offset,
                                   fpreal x_window_size, fpreal y_window_size,
                                   fpreal &cx, fpreal &cy,
                                   fpreal &hw, fpreal &hh);

//  member data access methods

    bool         isDirty() const        { return (myFlag.viewportDirty ||
                                                  myFlag.matrixDirty || 
                                                  myFlag.iMatrixDirty); }
    // bumped whenever the view has changed.
    int          getViewVersion() const { return myVersion + myVersion2D; }
    void         bumpViewVersion() { myVersion++; }
    void         bumpView2DVersion() { myVersion2D++; }
    int          getView3DVersion() const { return myVersion; }
    int          getView2DVersion() const { return myVersion2D; }
    
    // projection
    int          initialized() const            { return myFlag.initXform;    }
    int          getOrthoFlag() const           { return myFlag.ortho;        }
    void         setOrthoFlag(int o)            { myFlag.ortho = o;           }

    void         setInfiniteFarPlane(bool enable) { myInfiniteFarPlane = enable;}
    bool         getInfiniteFarPlane() const { return myInfiniteFarPlane; }
    void         setLimits(fpreal n, fpreal f) { setNearClip(n); setFarClip(f); }
    void         getLimits(fpreal *n, fpreal* f)
                 {
                     *n = myView.myNearLimit;
                     *f = myView.myFarLimit;
                 }
    void         setNearClip(fpreal near);
    void         setFarClip(fpreal far);
    fpreal       getNearClip() const { return myView.myNearLimit; }
    fpreal       getFarClip() const { return myView.myFarLimit; }

    void         setSceneBounds(const UT_BoundingBoxD &b)
                      { mySceneBounds=b; }
    const UT_BoundingBoxD &getSceneBounds() const { return mySceneBounds; }
    void         setSelectedObjectBounds(const UT_BoundingBoxD &b)
                      { mySelectedObjBounds=b; }

    // In case far/near > 10M, and extended zbuffer range is supported
    // Far clip will be at this value rather than 1.0.
    fpreal32     getExtendedZBufferFar() const { return myExtendedZBufferFar; }

    static void  setExtendedZBufferRangeSupport(bool has_ext);

    void         allowNearFarClipAdapt(bool allow)
                 { myAllowNearFarClipAdapt = allow; }

    // True if the viewer isn't tied to a camera.
    void         setIsFreeCam(bool free_cam) { myIsFreeCam = free_cam; }
    bool         isFreeCam() const           { return myIsFreeCam; }

    void         setWindow(fpreal x, fpreal y, fpreal w, fpreal h)
                 {
                     myView.myWinX = x;
                     myView.myWinY = y;
                     myView.myWinW = SYSmax(w, fpreal(0.001));
                     myView.myWinH = SYSmax(h, fpreal(0.001));
                     updateWindowOverridesNominal();
                 }
    void         getWindow(fpreal &x, fpreal &y,
                           fpreal &w, fpreal &h) const
                 {
                     x = myView.myWinX;
                     y = myView.myWinY;
                     w = myView.myWinW;
                     h = myView.myWinH;
                 }

    void         setNominalWindow(fpreal x, fpreal y, fpreal w, fpreal h)
                 {
                     myNominalWinX = x;
                     myNominalWinY = y;
                     myNominalWinW = SYSmax(w, fpreal(0.001));
                     myNominalWinH = SYSmax(h, fpreal(0.001));
                     updateWindowOverridesNominal();
                 }
    void         getNominalWindow(fpreal &x, fpreal &y,
                                  fpreal &w, fpreal &h) const
                 {
                     x = myNominalWinX;
                     y = myNominalWinY;
                     w = myNominalWinW;
                     h = myNominalWinH;
                 }
    bool         doesWindowOverrideNominal() const
                 { return myWindowOverridesNominal; }

    // A handy method to compute the view region bounds relative to the nominal
    // window rather than relative to the current window.  With bounds relative
    // to the nominal window, the nominal window is the unit square from (0,0)
    // to (1,1), in contrast with bounds relative to the current window, which
    // are themselves always this unit square.
    void         getViewBoundsRelativeToNominalWindow(
                        fpreal &l, fpreal &r, fpreal &b, fpreal &t) const;

    // The window is stored as an offset from 0, 0 with the scale applied prior
    // to translation.  However, mantra and other renderers expect the window
    // to be relative to the (0,1) rectangle.  getScreenWindow() will translate
    // the window parameters into a screen window.  setScreenWindow() will take
    // a screen window and set the appropriate parameters.
    void         getScreenWindow(fpreal &l, fpreal &r,
                                 fpreal &b, fpreal &t) const
                 {
                     convertViewToScreenWindow(myView.myWinX, myView.myWinY,
                                               myView.myWinW, myView.myWinH,
                                               l, r, b, t);
                 }
    void         setScreenWindow(fpreal l, fpreal r, fpreal b, fpreal t)
                 {
                     convertScreenToViewWindow(l, r, b, t,
                                               myView.myWinX, myView.myWinY,
                                               myView.myWinW, myView.myWinH);
                 }

    void         setSubRegion(fpreal x, fpreal y, fpreal w, fpreal h)
                 {
                     myHasSubRegion = true;
                     mySubRegionX = x;
                     mySubRegionY = y;
                     mySubRegionW = w;
                     mySubRegionH = h;
                 }
    void         clearSubRegion()
                 {
                     myHasSubRegion = false;
                     mySubRegionX = 0.0;
                     mySubRegionY = 0.0;
                     mySubRegionW = 1.0;
                     mySubRegionH = 1.0;
                 }
    bool         getSubRegion(fpreal &x,fpreal &y,fpreal &w, fpreal &h) const
                 {
                     x = mySubRegionX;
                     y = mySubRegionY;
                     w = mySubRegionW;
                     h = mySubRegionH;
                     return myHasSubRegion;
                 }
    bool         hasSubRegion() const { return myHasSubRegion; }

    static void  convertScreenToViewWindow(
                        fpreal l, fpreal r, fpreal b, fpreal t,
                        fpreal &xoff, fpreal &yoff, fpreal &xsize, fpreal &ysz);
    static void  convertViewToScreenWindow(
                        fpreal xoff, fpreal yoff, fpreal xsize, fpreal ysize,
                        fpreal &l, fpreal &r, fpreal &b, fpreal &t);

    fpreal       getWinSizeX() const    { return myView.myWinW; }
    fpreal       getWinSizeY() const    { return myView.myWinH; }
    fpreal       getWinX() const        { return myView.myWinX; }
    fpreal       getWinY() const        { return myView.myWinY; }

    enum GUI_ViewAdjustLimits
    {
        GUI_VIEW_ADJUST_NONE = 0,
        GUI_VIEW_ADJUST_FAR  = 1,
        GUI_VIEW_ADJUST_NEAR = 2,
        GUI_VIEW_ADJUST_BOTH = 3
    };
    void         setAdjustLimits(GUI_ViewAdjustLimits which)
                                                { myAdjustLimits = which;    }
    GUI_ViewAdjustLimits getAdjustLimits() const { return myAdjustLimits; }

    void       setWindowAffectRotoscope(int v)  { myFlag.rotoTrackWindow = v; }
    int          rotoscopeTracksWindowVals() const 
                                            { return myFlag.rotoTrackWindow; }

    // aspectRatio
    void         setApplyAspectFlag(int a)      { myFlag.applyAspect = a;     }
    int          getApplyAspectFlag() const     { return myFlag.applyAspect;  }
    void         setAspectRatio(fpreal a)       { myViewAspectRatio = a;      }
    fpreal       getAspectRatio() const         { return myViewAspectRatio;   }

    void         setFrustumScale(fpreal xsc, fpreal ysc)
                 {
                     myFrustumWidthScale  = xsc;
                     myFrustumHeightScale = ysc;
                 }

    // Return 8 corner points of the frustum, near points first (BL,BR,TL,TR)
    void         getFrustumPoints(UT_Vector3FArray &pnts);

    // position
    SYS_FORCE_INLINE
    void                setT(const UT_Vector3D &t)
            { myView.myT = t; myFlag.matrixDirty=1; myFlag.iMatrixDirty=1;}
    SYS_FORCE_INLINE
    const UT_Vector3D & getT() const   { return myView.myT; }

    // pivot
    SYS_FORCE_INLINE
    const UT_Vector3D & getP() const   { return myView.myP; }
    SYS_FORCE_INLINE
    void                setP(const UT_Vector3D &p)
            { myView.myP = p; myFlag.matrixDirty=1; myFlag.iMatrixDirty=1;}

    static void         setOrientationMode(orientation o);
    static orientation  getOrientationMode();
    static bool         isOrientationYUp()
                            { return getOrientationMode() == Y_UP; }
    static bool         isOrientationZUp()
                            { return getOrientationMode() == Z_UP; }

    // Rotation style:
    static void  setTumbleStyleFlag(int style)
                 { myTumbleStyle = style; }
    static int   getTumbleStyleFlag() { return myTumbleStyle; }
    static void  setAltKeyViewControlsFlag(int style)
                 { myAltKeyViewControls = style; }
    static int   getAltKeyViewControlsFlag() { return myAltKeyViewControls; }
    static void  setScrollStyleFlag(int style)
                 { myScrollStyle = style; }
    static int   getScrollStyleFlag() { return myScrollStyle; }
    static void  setDefaultHomingStyleFlag(int style)
                 { myDefaultHomingStyle = GUI_ViewParameter::axis(style); }
    static axis  getDefaultHomingStyleFlag() { return myDefaultHomingStyle; }

    // the resulting matrices
    void         setRotateMatrix(const UT_Matrix3D &mat) 
                                                { myView.myRotateMatrix = mat;
                                                  myFlag.matrixDirty = 1;
                                                  myFlag.iMatrixDirty = 1;    
                                                  myFlag.rxyzDirty = 1;       }
    const UT_Matrix4D &getRotateMatrix() const { return myView.myRotateMatrix; }

    const UT_Matrix4D &getProjectionMatrix() const
            { return myProjectionOverride ? *myProjectionOverride
                                          : myView.myProjectionMatrix;  }
    const UT_Matrix4D &getTransformMatrix()     { updateTransformMatrix();
                                                  return myTransformMatrix;   }
    const UT_Matrix4D &getItransformMatrix()    { updateItransformMatrix();
                                                  return myItransformMatrix;  }

    // This sets the transform matrix to the given value, bypassing the
    // PX, TX, etc.  The purpose of this is to get accurate camera transforms
    // you can first set all the PX, Rotate, etc, according to the cracked
    // values, and then do a forceTransformMatrix to ensure the user sees
    // the most accurate possible matrix.
    void         forceTransformMatrix(const UT_DMatrix4 &mat);
    void         getTransformMatrix(UT_DMatrix4 &mat, fpreal time);
    void         setTransformCallback(GUI_TransformCallback callback,
                                      void *data)
                 {
                     myTransformCallback = callback;
                     myTransformCallbackData = data;
                 }

    // Class I/O methods.  They return 0 if successful, -1 if not.
    // `for_view_copy` is only for temporarily transferring one view parms to
    // another.
    int          save(std::ostream &os,
                      char separator = '\n',
                      bool for_view_copy = false) const;
    bool         load(UT_IStream &is);
    bool         oldLoad(UT_IStream &is, int version);

    // inline for non-virtual class
    const char  *className() const { return "GUI_ViewParameter"; }

    fpreal       getLastHomeRadius() const      { return myLastHomeRadius;    }

    void         setHomeAxis(axis homeaxis)
                    { myHomeAxis = homeaxis; myFlag.rxyzDirty = 1; }
    axis         getHomeAxis() const { return myHomeAxis; }
    void         setCustomHomeRot(UT_Matrix3R &rot) { myCustomHomeRot = rot; }
    const UT_Matrix3R   &getCustomHomeRot() const { return myCustomHomeRot; }

    // Set a callback to get the home rotation for the construction plane
    // (axis::CPLANE), to which this class does not have direct access.
    void         setCPlaneHomeRotCallback(GUI_HomeRotCallback callback,
                                          void *data)
                 {
                     myCPlaneHomeRotCallback = callback;
                     myCPlaneHomeRotCallbackData = data;
                 }


    void         setOrthoWidth(fpreal w) { myView.myOrthoWidth = w; }
    fpreal       getOrthoWidth() const  { return myView.myOrthoWidth; }
    
    void         setFocalLength(fpreal f) { myView.myFocalLength = f; }
    fpreal       getFocalLength() const { return myView.myFocalLength; }
    
    void         setFocalUnitScale(fpreal f) { myView.myFocalScale = f; }
    fpreal       getFocalUnitScale() const   { return myView.myFocalScale; }
    
    void         setFocusDistance(fpreal f) { myView.myFocusDistance = f; }
    fpreal       getFocusDistance() const   { return myView.myFocusDistance; }
    
    void         setAperture(fpreal a)  { myView.myAperture = a; }
    fpreal       getAperture() const    { return myView.myAperture; }
 
    void         setFStop(fpreal fs)    { myView.myFStop = fs; }
    fpreal       getFStop() const       { return myView.myFStop; }

    void         setApertureOffsets(fpreal h, fpreal v)
                     {
                         myView.myHApertureOffset = h; 
                         myView.myVApertureOffset = v;
                     }
    void         getApertureOffsets(fpreal &h, fpreal &v) const
                     {
                         h = myView.myHApertureOffset; 
                         v = myView.myVApertureOffset;
                     }

    fpreal       getNearLimit() const   { return myView.myNearLimit; }
    fpreal       getFarLimit() const    { return myView.myFarLimit; }

    fpreal       getZBufferNear() const { return myZBufferNear; } 
    fpreal       getZBufferFar() const  { return myZBufferFar; } 

  // viewport clearing
    fpreal       myClear;

  // fog
    int          myFog;
    float        myFogDensity;
    float        myFogNear;
    float        myFogFar;
    float        myFogColor[3];
    float        myFogAlpha;

  // used for rotoscoping only
    fpreal       myWinRoll;

    // container for all view home information 
    class gui_View
    {
    public:
        gui_View()
            : myT(0.0, 0.0, 0.1),
              myP(0.0, 0.0, 0.0),
              myRotateMatrix(1.0),
              myProjectionMatrix(1.0),
              myWinX(0.0),
              myWinY(0.0),
              myWinW(1.0),
              myWinH(1.0),
              myOrthoWidth(1.0),
              myFocalLength(50.0),
              myFocusDistance(5.0),
              myAperture(41.4214),
              myFStop(5.6),
              myFocalScale(0.001),
              myNearLimit(0.1),
              myFarLimit(10000.0),
              myHApertureOffset(0.0),
              myVApertureOffset(0.0),
              myDefaultFOV(45.0)
            {}
        
        UT_Vector3D      myT;
        UT_Vector3D      myP;

        UT_Matrix4D      myRotateMatrix;
        UT_Matrix4D      myProjectionMatrix;
        
        // window (zooming)
        fpreal myWinX;
        fpreal myWinY;
        fpreal myWinW;
        fpreal myWinH;
        
        // projection information
        // ortho specific
        fpreal   myOrthoWidth;
        
        // perspective specific sSee diagram below)
        fpreal   myFocalLength;
        fpreal   myFocusDistance;
        fpreal   myAperture;
        fpreal   myFStop; // for dof.
        fpreal   myFocalScale;
        fpreal   myHApertureOffset;
        fpreal   myVApertureOffset;
        fpreal   myDefaultFOV;
  
        fpreal   myNearLimit;
        fpreal   myFarLimit;
    };
    
    // methods to quickly stash and recall the view state.
    void         getViewState(gui_View &view_state) const
                     { view_state = myView; }
    void         setViewState(const gui_View &view_state)
                    {
                        myView = view_state;
                        myFlag.matrixDirty=1;
                        myFlag.iMatrixDirty=1;
                        myFlag.rxyzDirty=1;
                        updateWindowOverridesNominal();
                    }

    void         adjustNearFarClip();

  // clipping
private:
    fpreal       myZBufferNear;
    fpreal       myZBufferFar;
    GUI_ViewAdjustLimits  myAdjustLimits;
    bool         myInfiniteFarPlane = false;
    bool         myIsFreeCam = true;

  // aspect ratio
    fpreal       myViewAspectRatio;
public:
    fpreal       myPixelAspect; // depends on output device

// projection information (see docs below)
    fpreal       myAdjustedNear;
    fpreal       myAdjustedFar;
    fpreal       myAdjustedX;
    fpreal       myAdjustedY;
    fpreal       myAdjustedW;
    fpreal       myAdjustedH;
    fpreal       myFullW;
    fpreal       myFullH;
    fpreal       myFrustumWidthScale;
    fpreal       myFrustumHeightScale;

    fpreal       myLastZoomDelta;
    
private:
    void         updateTransformMatrix();
    void         updateItransformMatrix();
    void         updateRXYZValues();
    fpreal       getDistanceToBoxCenter(int clamp = 0) const;

    void         internalScroll(fpreal dx, fpreal dy,
                                const UT_InclusiveRect &viewport,
                                bool decouple_axes,
                                const UT_Vector3R *locked_pos);
    void         internalZoom(fpreal dx, GUI_ZoomItem item, int width);
    void         internalOffsetZoom(fpreal sx, fpreal sy, fpreal dx,
                                    GUI_ZoomItem item,
                                    const UT_InclusiveRect &viewport);
    void         internalScreenScroll(fpreal dx, fpreal dy,
                                      const UT_InclusiveRect &viewport);

    void         getFrustumClip(fpreal &l, fpreal &r, fpreal &t, fpreal &b,
                                fpreal &n, fpreal &f, bool adjust_zrange);
    bool         computeWorldLockedScrollAccel(fpreal dx, fpreal dy,
                                               const UT_Vector3R &locked_pos,
                                               fpreal &accelerationx,
                                               fpreal &accelerationy);
    fpreal       computeZoomDelta(fpreal dx,
                                  bool precise_zoom,
                                  bool smooth_deltas);

    void         updateWindowOverridesNominal()
                 {
                     myWindowOverridesNominal =
                         (myView.myWinX != myNominalWinX ||
                          myView.myWinY != myNominalWinY ||
                          myView.myWinW != myNominalWinW ||
                          myView.myWinH != myNominalWinH);
                 }

    GUI_ViewFlag myFlag;

// transform information

    gui_View     myView;
    fpreal       myDx, myDy;
    static orientation myOrientationMode;
    static int   myTumbleStyle;
    static int   myAltKeyViewControls;
    static int   myScrollStyle;
    static axis  myDefaultHomingStyle;

    fpreal       myRx, myRy, myRz;      // Used by euler method.  In degrees

    // always call updateTransformMatrix before using myTransformMatrix.
    UT_Matrix4D  myTransformMatrix;     // this one is generated from the above
    UT_Matrix4D  myItransformMatrix;    // inverse of myTransformMatrix;

    GUI_TransformCallback        myTransformCallback;
    void                        *myTransformCallbackData;

// home information to be used in scaling of view transformation
    fpreal       myLastHomeDistance;
    fpreal       myLastHomePixelWidthOBSOLETE;
    fpreal       myLastHomeAdjustedBoxWidth;
    fpreal       myLastHomeOrthoWidth;
    fpreal       myLastHomeRadius;

    // myLastHomeAdjustedBoxWidth supercedes myLastHomePixelWidth, but to load
    // view transforms from old hip files without screwed up scrolling, we may
    // need to use the obsolete quantity until the next manual home operation.
    bool         myObsoleteScrollIsActive;

    axis         myHomeAxis;
    UT_Matrix3R  myCustomHomeRot;

    GUI_HomeRotCallback          myCPlaneHomeRotCallback;
    void                        *myCPlaneHomeRotCallbackData;

    // A collection of data needed for calculating the appropriate changes to
    // the view transform to perform view operations under continuous export
    // of view changes to a camera.
    class ContinuousExportCache
    {
    public:
        ContinuousExportCache() {}
        
        UT_Matrix4D      myRotateMatrix;
        UT_Matrix4D      myTransformMatrix;
        UT_Matrix4D      myItransformMatrix;
        fpreal           myAdjustedNear;
        fpreal           myAdjustedX;
        fpreal           myAdjustedY;
        fpreal           myTotalScrollX;
        fpreal           myTotalScrollY;
    };

    typedef ContinuousExportCache        ViewOpCache;

    ViewOpCache  myContinuousExportCache;
    bool         myContinuousExportInProgress;

    // The nominal window (zooming) for this view.  The myView.myWin* members
    // represent the window used for the current view, but when they are used
    // to override the camera's screen window, we need to know that this is
    // the case and what nominal window values to use for properly displaying
    // overlays like the safe area or field guide.
    bool         myWindowOverridesNominal;
    fpreal       myNominalWinX;
    fpreal       myNominalWinY;
    fpreal       myNominalWinW;
    fpreal       myNominalWinH;

    bool         myHasSubRegion;
    fpreal       mySubRegionX;
    fpreal       mySubRegionY;
    fpreal       mySubRegionW;
    fpreal       mySubRegionH;

    // These might be needed for other guys.
    int          myViewportLeft,   myViewportRight;
    int          myViewportBottom, myViewportTop;

    // The view is a subregion of the viewport that represents the current
    // "camera" view.  Aspect ratio bars are used to dim the parts of the
    // viewport not in this view.  The window coordinates are relative to
    // this view, not the viewport.
    int          myViewLeft,   myViewRight;
    int          myViewBottom, myViewTop;

    int          myVersion;
    int          myVersion2D;

    fpreal32     myExtendedZBufferFar;
    bool         myHasExtendedZBufferFar;
    bool         myAllowNearFarClipAdapt;
    UT_BoundingBoxD  mySceneBounds;
    UT_BoundingBoxD  mySelectedObjBounds;

    UT_Matrix4D  *myProjectionOverride;
};


#ifdef __DOCUMENTATION__

FOV can be computed from aperture and focal length.

        <--aperture--->
        |             |
        |             |
        +------+------+-----------
         \     |     /           ^
          \    |    /            |
           \_--+--_/           Focal
Unzoomed    \  |  /            Length
     FOV --> \ | /               |
              \|/                v
               +------------------

myFullW and myFullH are the dimensions of the plane onto which the
image is projected before any adjustments for zoom or window parms.
the plane is located at "myAdjustedNear" along the z axis.
After taking the zoom and win channels into account, myAdjustedX and
myAdjustedY refer to the center of the view on the same plane, and
myAdjustedW and myAdjustedH contain the dimensions of the adjusted view.

#endif

#endif