UT_CameraParms.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.
 *
 * COMMENTS:
 *      A minimalist representation of a camera's parms (except transform).
 *
 */

#ifndef __UT_Camera_h__
#define __UT_Camera_h__

#include "UT_API.h"
#include "UT_Options.h"
#include "UT_VectorTypes.h"
#include <stdlib.h>
#include <SYS/SYS_Types.h>

class UT_JSONParser;
class UT_JSONValue;
class UT_JSONWriter;

// Projections for cameras.
// Using the "OBJ" naming for historical reasons.
enum OBJ_ProjectionType
{
    OBJ_PROJ_PERSPECTIVE,
    OBJ_PROJ_ORTHO,
    NUM_OBJ_PROJECTIONS
};

class UT_API UT_CameraParms
{
public:
                        UT_CameraParms()
                        { setDefaults(); }

    void                setDefaults();

    fpreal              focal;                  // Focal length
    fpreal              aperture;               // Aperture
    fpreal              pixelaspect;            // Aspect ratio
    fpreal              focusdistance;          // Focus distance
    fpreal              fstop;                  // F-Stop;
    fpreal              imagingdistance;        // imaging distance
    fpreal              cropx[2];               // Min max for cropping in x
    fpreal              cropy[2];               // Min max for cropping in y
    fpreal              winx[2];                // Sub-windowing in X
    fpreal              winy[2];                // Sub-windowing in Y
    fpreal              clipnear, clipfar;      // Near/Far clipping planes
    fpreal              shutteropen;            // Shutter open
    fpreal              shutterclose;           // Shutter close
    fpreal              orthozoom;              // Orthographic zoom
    fpreal              guidescale;             // Scale of the Camera Display

    exint               resx, resy;             // Resolution for camera
    
    OBJ_ProjectionType  projection;             // Camera Projection
    UT_OptionsHolder    metadata;               // Custom Metadata


    /// @{
    /// Methods to get and set the parameters with UT_Options.
    UT_Options          getOptions() const;
    void                setFromOptions(const UT_Options *options);
    /// @}

    /// @{
    /// Methods to serialize the parameters to a JSON stream:
    /// @code
    ///     "aperture":41.42136,
    ///     "pixelaspect":1,
    ///     "clipnear": 0.001
    ///     "clipfar" :1000000,
    ///     "cropmax":[1,1],
    ///     "cropmin":[0,0],
    ///     "focal":50,
    ///     "focusdistance":10,
    ///     "fstop":22.1,
    ///     "orthozoom":1,
    ///     "guidescale": 1,
    ///     "imagingdistance": 1,
    ///     "projection":"perspective",
    ///     "resolutionx" :320,
    ///     "resolutiony" : 243,
    ///     "shutteropen" : 0
    ///     "shutterclose": 0,
    ///     "windowmax":[1,1],
    ///     "windowmin":[0,0]
    ///     "metadata": {}
    /// @endcode
    bool                save(UT_JSONWriter &w) const;
    bool                save(UT_JSONValue &v) const;
    bool                load(UT_JSONParser &p);
    /// @}

    bool operator==(const UT_CameraParms &other) const;
    bool operator!=(const UT_CameraParms &other) const
    {
        return !(*this == other);
    }
    /// adds the float parameters together
    /// which means everything but 
    /// - resolution
    /// - metadata
    /// - projection
    UT_CameraParms &operator+=(const UT_CameraParms &other);
    /// same as above but multiplies float parameters by multiplier
    UT_CameraParms &operator*=(const fpreal multiplier);

    /// @{
    /// Methods to serialize a 3D camera to a JSON stream:
    /// @code
    /// {
    ///     "camera":{
    ///         "aperture":41.42136,
    ///         "aspect":1,
    ///         "clipnear": 0.001,
    ///         "clipfar": 1000000,
    ///         "cropmax":[1,1],
    ///         "cropmin":[0,0],
    ///         "focal":50,
    ///         "focusdistance":10,
    ///         "fstop":22.1,
    ///         "orthozoom":1,
    ///         "guidescale":1,
    ///         "imagingdistance": 1
    ///         "projection":"perspective",
    ///         "resolutionx":320,
    ///         "resolutiony":243,
    ///         "shutteropen":0,
    ///         "shutterclose":0,
    ///         "windowmax":[1,1],
    ///         "windowmin":[0,0]
    ///         "metadata": {}
    ///     },
    ///     "position":[0,0,0],
    ///     "transform":[1,0,0,0,1,0,0,0,1]
    /// }
    /// @endcode
    static bool         save3DCamera(UT_JSONWriter &w,
                                     const UT_Vector3D &position,
                                     const UT_Matrix3D &transform,
                                     const UT_CameraParms &parms);
    static bool         load3DCamera(UT_JSONParser &p,
                                     UT_Vector3D &position,
                                     UT_Matrix3D &transform,
                                     UT_CameraParms &parms);
    /// @}

    static const char *getProjectionToken(OBJ_ProjectionType projection);
    static OBJ_ProjectionType getProjectionEnum(const char *token);
    
    ///@{
    /// Convenience functions
    fpreal getAspectRatio() const
    {
        return (fpreal)(resx) / (fpreal)(resy);
    }
    void getWindowSize(fpreal &x, fpreal &y) const
    {
        x = winx[1] - winx[0]; 
        y = winy[1] - winy[0];
    }

    void getWindowCenter(fpreal &x, fpreal &y) const
    {
        x = (winx[0] + winx[1]) * 0.5 - 0.5;
        y = (winy[0] + winy[1]) * 0.5 - 0.5;
    }
    /// sets the window from a window offset and a window size
    void setWindow(fpreal x, fpreal y, fpreal sizex, fpreal sizey)
    {
        sizex *= .5;
        sizey *= .5;
        x += .5;
        y += .5;
        winx[0] = x - sizex;
        winx[1] = x + sizex;
        winy[0] = y - sizey;
        winy[1] = y + sizey;
    }
    /// returns true if the camera is orthographic
    bool isOrthographic() const
    {
        return projection == OBJ_PROJ_ORTHO;
    }
    
    ///@}

};

UT_API size_t
UTformatBuffer(char *buffer, size_t buffer_size, const UT_CameraParms &camp);

#endif // __UT_Camera_h__