CWE-ou-minkata/Sources/Plasma/CoreLib/plViewTransform.h

/*==LICENSE==*

CyanWorlds.com Engine - MMOG client, server and tools
Copyright (C) 2011  Cyan Worlds, Inc.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

You can contact Cyan Worlds, Inc. by email legal@cyan.com
 or by snail mail at:
      Cyan Worlds, Inc.
      14617 N Newport Hwy
      Mead, WA   99021

*==LICENSE==*/
#ifndef plViewTransform_inc
#define plViewTransform_inc

#include "hsMatrix44.h"
#include "hsGeometry3.h"
#include "hsPoint2.h"

class hsBounds3;
class hsStream;

// There's a lot here, but there's a lot one might want to do with view transforms.
// It's easiest to grab the structure thinking of it in terms of the different
// spaces you might want a point in. The ones supported here are:
//      Screen - this is actual pixel values
//      NDC - Normalized Device Coordinates, these are post W divide, so the
//          valid range is x = [-1..1], y = [-1..1], z = [0..1]
//      Camera - relative to the camera, with (0,0,-1) directly in front of the camera,
//          and (0, 1, 0) directly above the camera.
//      World - Universal world space.
//      Map - arbitrary mapping of NDC. Like from [(-1,-1,0)..(1,1,1)] => [(0,0,0)..(1,1,1)] (default).
//  Note that there is no object space here. There could be, but I wanted something more constant, more
//      world independent, so the ViewTransform remains constant unless the view changes. Whatever.
//
//  So we're broken into functional sections:
//  1) Queries on the state of this view transform, properties, matrix values, whatever. Note that you
//      generally shouldn't be reading a value (e.g. matrix) out of the ViewTransform, but let the
//      ViewTransform perform the operation you would with the matrix.
//  2) Setting state, properties, matrix values, whatever. There's a couple of really bizarre variants
//      (like the union and intersection of view frustums). Full support is available for perspective
//      or orthogonal views. An additional capability (not necessary) is offset transforms, useful
//      for rendering textures. If you don't what good they are, they probably aren't any good to you.
//  3) Conversions of points from one space to another. You may notice that there are a whole lot of them.
//      There is a conversion from each of the spaces above to each of the other spaces. That's 12
//      transformations right there. But Points and Vectors actually transform differently, so there
//      are different versions for those. Where they could be treated the same, there is an hsScalarTriple
//      version that does the actual work, and then casting versions to come and go from the right type.
//  4) Read and write (note these are NOT virtual).
//
//  More Notes:
//      This class has no virtual functions.
//      You must set the width and height for Screen queries to work (duh!).
//      ViewPort defaults to cover the entire width and height. Viewport only affects mapping, not clipping
//          (i.e. reducing the viewport width will still render the same stuff, just skinnier).
//      The actual data here is very small, this is mostly a collection of functions, so where possible,
//          just keep one of these to pass around, (e.g. rather than keeping track of FOV etc and passing
//          those around).
//
class plViewTransform
{
public:
    plViewTransform();
    ~plViewTransform() {}

    void                Reset(); // resets to default state

    // Queries
    hsBool              GetOrthogonal() const { return IHasFlag(kOrthogonal); }
    hsBool              GetPerspective() const { return !GetOrthogonal(); }
    hsBool              GetViewPortRelative() const { return IHasFlag(kViewPortRelative); }

    // Next, all our matrices.
    const hsMatrix44&   GetCameraToWorld() const { return fCameraToWorld; }
    const hsMatrix44&   GetWorldToCamera() const { return fWorldToCamera; }
    const hsMatrix44&   GetCameraToNDC() const { return ICheckCameraToNDC(); }
    const hsMatrix44&   GetWorldToNDC() const { return ICheckWorldToNDC(); }

    hsPoint3            GetPosition() const { return GetCameraToWorld().GetTranslate(); }
    hsVector3           GetDirection() const { return *((hsVector3 *)&GetWorldToCamera().fMap[2]); }
    hsVector3           GetUp() const { return *((hsVector3*)&GetWorldToCamera().fMap[1]); }
    hsVector3           GetAcross() const { return *((hsVector3*)&GetWorldToCamera().fMap[0]); }

    UInt16              GetScreenWidth() const { return fWidth; }
    UInt16              GetScreenHeight() const { return fHeight; }

    void                GetViewPort(hsPoint2& mins, hsPoint2& maxs) const;
    void                GetViewPort(int& loX, int& loY, int& hiX, int& hiY) const;
    int                 GetViewPortWidth() const { return GetViewPortRight() - GetViewPortLeft(); }
    int                 GetViewPortHeight() const { return GetViewPortBottom() - GetViewPortTop(); }
    int                 GetViewPortLeft() const { return int(GetViewPortLoX()); }
    int                 GetViewPortTop() const { return int(GetViewPortLoY()); }
    int                 GetViewPortRight() const { return int(GetViewPortHiX()); }
    int                 GetViewPortBottom() const { return int(GetViewPortHiY()); }
    float               GetViewPortLoX() const { return GetViewPortRelative() ? fViewPortX.fX * fWidth : fViewPortX.fX; }
    float               GetViewPortLoY() const { return GetViewPortRelative() ? fViewPortY.fX * fHeight : fViewPortY.fX; }
    float               GetViewPortHiX() const { return GetViewPortRelative() ? fViewPortX.fY * fWidth : fViewPortX.fY; }
    float               GetViewPortHiY() const { return GetViewPortRelative() ? fViewPortY.fY * fHeight : fViewPortY.fY; }

    hsPoint3            GetMapMin() const { return fMapMin; }
    hsPoint3            GetMapMax() const { return fMapMax; }
    void                GetMapping(hsPoint3& mapMin, hsPoint3& mapMax) const { mapMin = fMapMin; mapMax = fMapMax; }

    hsScalar            GetFovX() const;
    hsScalar            GetFovY() const;
    hsScalar            GetFovXDeg() const { return hsScalarRadToDeg(GetFovX()); }
    hsScalar            GetFovYDeg() const { return hsScalarRadToDeg(GetFovY()); }
    hsScalar            GetOrthoWidth() const { return fMax.fX - fMin.fX; }
    hsScalar            GetOrthoHeight() const { return fMax.fY - fMin.fY; }
    hsScalar            GetHither() const { return fMin.fZ; }
    hsScalar            GetYon() const { return fMax.fZ; }
    void                GetDepth(hsScalar& hither, hsScalar& yon) const { hither = GetHither(); yon = GetYon(); }

    // Setup.
    // First, our world to camera and back again.
    void                SetCameraTransform(const hsMatrix44& w2c, const hsMatrix44& c2w) { fWorldToCamera = w2c; fCameraToWorld = c2w; ISetFlag(kWorldToNDCSet, false); }

    // Next, what kind of projection.
    void                SetOrthogonal(hsBool on) { ISetFlag(kOrthogonal, on); InvalidateTransforms(); }
    void                SetPerspective(hsBool on) { SetOrthogonal(!on); }

    // Next, setting the scree/window/rendertarget size
    void                SetWidth(UInt16 w) { fWidth = w; }
    void                SetHeight(UInt16 h) { fHeight = h; }
    void                SetScreenSize(UInt16 w, UInt16 h) { SetWidth(w); SetHeight(h); }

    // Next, setting the viewport. You only need to do this if you want to use the screen functions above.
    // If you're passing in and getting out normalized device coordinates, skip this. If you don't set viewport,
    // Defaults to 0,0,width,height (i.e. the whole screen).
    void                SetViewPort(const hsPoint2& mins, const hsPoint2& maxs, hsBool relative=true);
    void                SetViewPort(float loX, float loY, float hiX, float hiY, hsBool relative=true) { SetViewPort(hsPoint2().Set(loX, loY), hsPoint2().Set(hiX, hiY), relative); }
    void                SetViewPort(UInt16 left, UInt16 top, UInt16 right, UInt16 bottom) { SetViewPort(hsScalar(left), hsScalar(top), hsScalar(right), hsScalar(bottom), false); }

    void                SetMapping(const hsPoint3& mins, const hsPoint3& maxs) { SetMapMin(mins); SetMapMax(maxs); }
    void                SetMapMin(const hsPoint3& mins) { fMapMin = mins; }
    void                SetMapMax(const hsPoint3& maxs) { fMapMax = maxs; }

    // Next, variants on setting up our projection matrix.
    // Depth is pretty uniform.
    void                SetDepth(hsScalar hither, hsScalar yon) { fMin.fZ = hither; fMax.fZ = yon; InvalidateTransforms(); }
    void                SetDepth(const hsPoint2& d) { SetDepth(d.fX, d.fY); }
    void                SetHither(hsScalar hither) { fMin.fZ = hither; InvalidateTransforms(); }
    void                SetYon(hsScalar yon) { fMax.fZ = yon; InvalidateTransforms(); }

    // Garden variety symmetric fov uses either of this first batch. Unless you're doing some funky projection, you don't even
    // need to look through the rest.
    // Degrees - all are full angles, < 180 degrees
    void                SetFovDeg(const hsPoint2& deg) { SetFovDeg(deg.fX, deg.fY); }
    void                SetFovDeg(hsScalar degX, hsScalar degY) { SetFovXDeg(degX); SetFovYDeg(degY); }
    void                SetFovXDeg(hsScalar deg) { SetFovX(hsScalarDegToRad(deg)); }
    void                SetFovYDeg(hsScalar deg) { SetFovY(hsScalarDegToRad(deg)); }

    // Radians - all are full angles, < PI
    void                SetFov(const hsPoint2& rad) { SetFov(rad.fX, rad.fY); }
    void                SetFov(hsScalar radX, hsScalar radY) { SetFovX(radX); SetFovY(radY); }
    void                SetFovX(hsScalar rad) { SetHalfWidth(hsTan(rad * 0.5f)); }
    void                SetFovY(hsScalar rad) { SetHalfHeight(hsTan(rad * 0.5f)); }

    // For orthogonal projection, don't call SetWidth(hsTan(fovRads)), because hsTan(f)/2 != hsTan(f/2)
    // For non-centered, call SetWidths/Heights() directly.
    void                SetWidth(hsScalar w) { SetHalfWidth(w * 0.5f); }
    void                SetHeight(hsScalar h) { SetHalfHeight(h * 0.5f); }

    // The rest do no interpretation, just stuff the values passed in.
    void                SetHalfWidth(hsScalar hw) { SetWidths(-hw, hw); }
    void                SetHalfHeight(hsScalar hh) { SetHeights(-hh, hh); }
    void                SetWidths(hsScalar minW, hsScalar maxW) { fMin.fX = minW; fMax.fX = maxW; InvalidateTransforms(); }
    void                SetHeights(hsScalar minH, hsScalar maxH) { fMin.fY = minH; fMax.fY = maxH; InvalidateTransforms(); }
    void                SetWidths(const hsPoint2& w) { SetWidths(w.fX, w.fY); }
    void                SetHeights(const hsPoint2& h) { SetHeights(h.fX, h.fY); }
    void                SetView(const hsPoint3& mins, const hsPoint3& maxs) { fMax = maxs; fMin = mins; InvalidateTransforms(); }

    // Take a CAMERA SPACE bounding box and sets up the projection to just surround it.
    // Note this doesn't swivel the camera around to see the box, it offsets the projection.
    // Return false if there isn't a projection that will capture any of the bnd. This
    // can be from the bnd being behind the camera.
    hsBool              SetProjection(const hsBounds3& cBnd);
    hsBool              SetProjectionWorld(const hsBounds3& wBnd);

    // This lets you create insane projection matrices. Note that it won't change the answer on anything like
    // GetFov().
    void                PreMultCameraToNDC(const hsMatrix44& m) { fCameraToNDC = m * GetCameraToNDC(); }
    void                PostMultCameraToNDC(const hsMatrix44& m) { fCameraToNDC = GetCameraToNDC() * m; }
    void                Recalc() { InvalidateTransforms(); }

    // These do the obvious, constructing a single view that encompasses either the intersection or union
    // of what the two views will see. The boolean is performed in axis aligned camera space, which lines
    // up nicely with screen space. Note that this only makes sense for two ViewTransforms with identical
    // CameraToWorld's (which isn't checked).
    hsBool              Intersect(const plViewTransform& view);
    hsBool              Union(const plViewTransform& view);

    // Convenience to move from one space to another.
    // Screen means pixels - Default is mapping NDC -> [0..1]. Z value of pixel is NDC Z.
    // NDC is the ([-1..1],[-1..1],[0..1]) Normalized device coordinates.
    // Camera is camera space.
    // World is world space.
    // Past that, you're on your own.
    hsScalarTriple      ScreenToNDC(const hsScalarTriple& scrP) const;
    hsScalarTriple      ScreenToCamera(const hsScalarTriple& scrP) const { return NDCToCamera(ScreenToNDC(scrP)); }

    hsPoint3            ScreenToNDC(const hsPoint3& scrP) const { return hsPoint3(ScreenToNDC(hsScalarTriple(scrP))); }
    hsPoint3            ScreenToCamera(const hsPoint3& scrP) const { return hsPoint3(ScreenToCamera(hsScalarTriple(scrP))); }
    hsPoint3            ScreenToWorld(const hsPoint3& scrP) const { return CameraToWorld(ScreenToCamera(scrP)); }

    hsVector3           ScreenToNDC(const hsVector3& scrV) const { return hsVector3(ScreenToNDC(hsScalarTriple(scrV))); }
    hsVector3           ScreenToCamera(const hsVector3& scrV) const { return hsVector3(ScreenToCamera(hsScalarTriple(scrV))); }
    hsVector3           ScreenToWorld(const hsVector3& scrV) const { return CameraToWorld(ScreenToCamera(scrV)); }

    hsScalarTriple      NDCToScreen(const hsScalarTriple& ndc) const;
    hsScalarTriple      NDCToCamera(const hsScalarTriple& ndc) const;

    hsPoint3            NDCToScreen(const hsPoint3& ndc) const { return hsPoint3(NDCToScreen(hsScalarTriple(ndc))); }
    hsPoint3            NDCToCamera(const hsPoint3& ndc) const { return hsPoint3(NDCToCamera(hsScalarTriple(ndc))); }
    hsPoint3            NDCToWorld(const hsPoint3& ndc) const { return CameraToWorld(NDCToCamera(ndc)); }

    hsVector3           NDCToScreen(const hsVector3& ndc) const { return hsVector3(NDCToScreen(hsScalarTriple(ndc))); }
    hsVector3           NDCToCamera(const hsVector3& ndc) const { return hsVector3(NDCToCamera(hsScalarTriple(ndc))); }
    hsVector3           NDCToWorld(const hsVector3& ndc) const { return CameraToWorld(NDCToCamera(ndc)); }

    hsScalarTriple      CameraToScreen(const hsScalarTriple& camP) const { return NDCToScreen(CameraToNDC(camP)); }
    hsScalarTriple      CameraToNDC(const hsScalarTriple& camP) const;

    hsPoint3            CameraToScreen(const hsPoint3& camP) const { return hsPoint3(CameraToScreen(hsScalarTriple(camP))); }
    hsPoint3            CameraToNDC(const hsPoint3& camP) const { return hsPoint3(CameraToNDC(hsScalarTriple(camP))); }
    hsPoint3            CameraToWorld(const hsPoint3& camP) const { return GetCameraToWorld() * camP; }

    hsVector3           CameraToScreen(const hsVector3& camP) const { return hsVector3(CameraToScreen(hsScalarTriple(camP))); }
    hsVector3           CameraToNDC(const hsVector3& camP) const { return hsVector3(CameraToNDC(hsScalarTriple(camP))); }
    hsVector3           CameraToWorld(const hsVector3& camV) const { return GetCameraToWorld() * camV; }

    hsPoint3            WorldToScreen(const hsPoint3& worldP) const { return (hsPoint3)CameraToScreen(WorldToCamera(worldP)); }
    hsPoint3            WorldToNDC(const hsPoint3& worldP) const { return CameraToNDC(WorldToCamera(worldP)); }
    hsPoint3            WorldToCamera(const hsPoint3& worldP) const { return GetWorldToCamera() * worldP; }

    hsVector3           WorldToScreen(const hsVector3& worldV) const { return (hsVector3)CameraToScreen(WorldToCamera(worldV)); }
    hsVector3           WorldToNDC(const hsVector3& worldP) const { return CameraToNDC(WorldToCamera(worldP)); }
    hsVector3           WorldToCamera(const hsVector3& worldV) const { return GetWorldToCamera() * worldV; }

    hsScalarTriple      NDCToMap(const hsScalarTriple& ndcP) const;
    hsScalarTriple      CameraToMap(const hsScalarTriple& camP) const { return NDCToMap(CameraToNDC(camP)); }

    hsPoint3            NDCToMap(const hsPoint3& ndcP) const { return hsPoint3(NDCToMap(hsScalarTriple(ndcP))); }
    hsPoint3            CameraToMap(const hsPoint3& camP) const { return hsPoint3(CameraToMap(hsScalarTriple(camP))); }
    hsPoint3            WorldToMap(const hsPoint3& worldP) const { return CameraToMap(WorldToCamera(worldP)); }

    hsVector3           NDCToMap(const hsVector3& ndcP) const { return hsVector3(NDCToMap(hsScalarTriple(ndcP))); }
    hsVector3           CameraToMap(const hsVector3& camP) const { return hsVector3(CameraToMap(hsScalarTriple(camP))); }
    hsVector3           WorldToMap(const hsVector3& worldP) const { return CameraToMap(WorldToCamera(worldP)); }

    void                Read(hsStream* s);
    void                Write(hsStream* s);

protected:
    enum
    {
        kNone               = 0x0,
        kOrthogonal         = 0x1,
        kSymmetric          = 0x2,
        kCameraToNDCSet     = 0x4,
        kWorldToNDCSet      = 0x8,
        kSetMask            = kCameraToNDCSet | kWorldToNDCSet,
        kViewPortRelative   = 0x10
    };

    mutable UInt32          fFlags;

    hsMatrix44              fCameraToWorld;
    hsMatrix44              fWorldToCamera;

    hsPoint3                fMin; // minTanX/X, minTanY/Y, hither
    hsPoint3                fMax; // maxTanX/X, maxTanY/Y, yon

    // Screen (or rendertarget) dimensions in pixels.
    UInt16                  fWidth; 
    UInt16                  fHeight;

    // Viewport can be stored as fraction of screen size, so the view transform's viewport
    // can be set up independent of the size of the window it's applied to. 
    hsPoint3        fViewPortX; // min, max, 1 / (max-min)
    hsPoint3        fViewPortY; // min, max, 1 / (max-min)

    // For arbitrary mapping (unconfined to pixel coords or NDC), just set what you want
    // to map to.
    hsPoint3        fMapMin;
    hsPoint3        fMapMax;

    // Some mutables. These are just the calculated from the above (e.g. fov, depth, perspective, etc).
    mutable hsMatrix44      fCameraToNDC;
    mutable hsMatrix44      fWorldToNDC;

    // Have to set a limit here on the smallest the hither plane can be.
    static const hsScalar   kMinHither;

    void                ISetCameraToNDC() const;
    hsBool              ICameraToNDCSet() const { return IHasFlag(kCameraToNDCSet); }
    const hsMatrix44&   ICheckCameraToNDC() const { if( !ICameraToNDCSet() ) ISetCameraToNDC(); return fCameraToNDC; }

    void                ISetWorldToNDC() const { fWorldToNDC = GetCameraToNDC() * fWorldToCamera; ISetFlag(kWorldToNDCSet); }
    hsBool              IWorldToNDCSet() const { return IHasFlag(kWorldToNDCSet); }
    const hsMatrix44&   ICheckWorldToNDC() const { if( !IWorldToNDCSet() ) ISetWorldToNDC(); return fWorldToNDC; }

    hsBool              IGetMaxMinsFromBnd(const hsBounds3& bnd, hsPoint3& mins, hsPoint3& maxs) const;

    void                InvalidateTransforms() { ISetFlag(kCameraToNDCSet|kWorldToNDCSet, false); }

    // Flags - generic
    hsBool              IHasFlag(UInt32 f) const { return 0 != (fFlags & f); }
    void                ISetFlag(UInt32 f, hsBool on=true) const { if(on) fFlags |= f; else fFlags &= ~f; }

};

#endif // plViewTransform_inc