Added function-based user-defined camera.

The syntax is `camera { user_defined location { FUNCTION_TRIPLET } direction { FUNCTION_TRIPLET } CAMERA_MODIFIERS }`. Instead of `{ FUNCTION_TRIPLET }`, a constant vector can be specified, and the usual defaults apply. Each `FUNCTION_TRIPLET` is a set of three functions, all taking as input parameters the image x and y position ranging from -0.5 (left/bottom) to +0.5 (right/top), and acting together to return a ray origin and direction for a given pixel. A direction of <0,0,0> indicates that the pixel is to be left black.

source/base/version.h

@@ -45,7 +45,7 @@
 #define OFFICIAL_VERSION_STRING "3.7.1"
 #define OFFICIAL_VERSION_NUMBER 371
 
-#define POV_RAY_PRERELEASE "alpha.8508492"
+#define POV_RAY_PRERELEASE "alpha.8509766"
 
 #if (POV_RAY_IS_AUTOBUILD == 1) && ((POV_RAY_IS_OFFICIAL == 1) || (POV_RAY_IS_SEMI_OFFICIAL == 1))
 #ifdef POV_RAY_PRERELEASE

source/core/coretypes.h

@@ -566,6 +566,33 @@ class GenericCustomFunction
         virtual RETURN_T Execute(GenericFunctionContextPtr pContext) = 0;
         virtual GenericCustomFunction* Clone() const = 0;
         virtual const FunctionSourceInfo* GetSourceInfo() const { return NULL; }
+
+        template<typename T1>
+        inline RETURN_T Execute(GenericFunctionContextPtr pContext, T1 arg1)
+        {
+            InitArguments(pContext);
+            PushArgument(pContext, arg1);
+            return Execute(pContext);
+        }
+
+        template<typename T1, typename T2>
+        inline RETURN_T Execute(GenericFunctionContextPtr pContext, T1 arg1, T2 arg2)
+        {
+            InitArguments(pContext);
+            PushArgument(pContext, arg1);
+            PushArgument(pContext, arg2);
+            return Execute(pContext);
+        }
+
+        template<typename T1, typename T2, typename T3>
+        inline RETURN_T Execute(GenericFunctionContextPtr pContext, T1 arg1, T2 arg2, T3 arg3)
+        {
+            InitArguments(pContext);
+            PushArgument(pContext, arg1);
+            PushArgument(pContext, arg2);
+            PushArgument(pContext, arg3);
+            return Execute(pContext);
+        }
 };
 
 typedef GenericCustomFunction<double, double> GenericScalarFunction;

source/core/math/vector.h

@@ -307,6 +307,16 @@ class GenericVector2d
         {
             return vect[X] * vect[X] + vect[Y] * vect[Y];
         }
+        inline bool IsNull() const
+        {
+            return (vect[X] == 0.0) &&
+                   (vect[Y] == 0.0);
+        }
+        inline bool IsNearNull(T epsilon) const
+        {
+            return (abs(vect[X]) < epsilon) &&
+                   (abs(vect[Y]) < epsilon);
+        }
         inline GenericVector2d normalized() const
         {
             T l = length();
@@ -522,6 +532,18 @@ class GenericVector3d
         {
             return vect[X] * vect[X] + vect[Y] * vect[Y] + vect[Z] * vect[Z];
         }
+        inline bool IsNull() const
+        {
+            return (vect[X] == 0.0) &&
+                   (vect[Y] == 0.0) &&
+                   (vect[Z] == 0.0);
+        }
+        inline bool IsNearNull(T epsilon) const
+        {
+            return (abs(vect[X]) < epsilon) &&
+                   (abs(vect[Y]) < epsilon) &&
+                   (abs(vect[Z]) < epsilon);
+        }
         inline GenericVector3d normalized() const
         {
             T l = length();

source/core/render/tracepixel.cpp

@@ -200,7 +200,8 @@ TracePixel::TracePixel(shared_ptr<SceneData> sd, const Camera* cam, TraceThreadD
                        focalBlurData(NULL),
                        maxTraceLevel(mtl),
                        adcBailout(adcb),
-                       pretrace(pt)
+                       pretrace(pt),
+                       mpFunctionContext(NULL)
 {
     SetupCamera((cam == NULL) ? sd->parsedCamera : *cam);
 }
@@ -209,6 +210,8 @@ TracePixel::~TracePixel()
 {
     if(focalBlurData != NULL)
         delete focalBlurData;
+    if (mpFunctionContext != NULL)
+        delete mpFunctionContext;
 }
 
 void TracePixel::SetupCamera(const Camera& cam)
@@ -246,6 +249,10 @@ void TracePixel::SetupCamera(const Camera& cam)
             aspectRatio = cameraLengthRight / cameraLengthUp;
             normalise = true;
             break;
+        case USER_DEFINED_CAMERA:
+            normalise = true;
+            mpFunctionContext = sceneData->functionContextFactory->CreateFunctionContext(threadData);
+            break;
         default:
             aspectRatio = cameraLengthRight / cameraLengthUp;
             break;
@@ -846,6 +853,31 @@ bool TracePixel::CreateCameraRay(Ray& ray, DBL x, DBL y, DBL width, DBL height,
             }
             break;
 
+        case USER_DEFINED_CAMERA:
+            // Convert the x coordinate to be a DBL from -0.5 to 0.5.
+            x0 = x / width - 0.5;
+
+            // Convert the y coordinate to be a DBL from -0.5 to 0.5.
+            y0 = 0.5 - y / height;
+
+            for (unsigned int i = 0; i < 3; ++i)
+            {
+                if (camera.Location_Fn[i] != NULL)
+                    cameraLocation[i] = camera.Location_Fn[i]->Execute(mpFunctionContext, x0, y0);
+                if (camera.Direction_Fn[i] != NULL)
+                    cameraDirection[i] = camera.Direction_Fn[i]->Execute(mpFunctionContext, x0, y0);
+            }
+            if (cameraDirection.IsNearNull(EPSILON))
+                return false;
+            ray.Origin    = cameraLocation;
+            ray.Direction = cameraDirection;
+
+            if(useFocalBlur)
+                JitterCameraRay(ray, x, y, ray_number);
+
+            InitRayContainerState(ray, true);
+            break;
+
         default:
             throw POV_EXCEPTION_STRING("Unknown camera type in CreateCameraRay().");
     }

source/core/render/tracepixel.h

@@ -128,6 +128,9 @@ class TracePixel : public Trace
         /// whether this is just a pretrace, allowing some computations to be skipped
         bool pretrace;
 
+        /// Function execution context for user-defined camera
+        GenericFunctionContextPtr mpFunctionContext;
+
         bool CreateCameraRay(Ray& ray, DBL x, DBL y, DBL width, DBL height, size_t ray_number);
 
         void InitRayContainerState(Ray& ray, bool compute = false);

source/core/scene/camera.cpp

@@ -251,6 +251,12 @@ void Camera::Init()
     Face_Distribution_Method = 0;
     Smooth = false;
     Max_Ray_Distance = 0.0;
+
+    for (unsigned int i = 0; i < 3; ++i)
+    {
+        Location_Fn[i]  = NULL;
+        Direction_Fn[i] = NULL;
+    }
 }
 
 /*****************************************************************************
@@ -360,6 +366,24 @@ Camera& Camera::operator=(const Camera& src)
     }
     Smooth = src.Smooth;
 
+    for (unsigned int i = 0; i < 3; ++i)
+    {
+        if (Location_Fn[i] != NULL)
+            delete Location_Fn[i];
+        if (src.Location_Fn[i] == NULL)
+            Location_Fn[i] = NULL;
+        else
+            Location_Fn[i] = src.Location_Fn[i]->Clone();
+
+        if (Direction_Fn[i] != NULL)
+            delete Direction_Fn[i];
+        if (src.Direction_Fn[i] == NULL)
+            Direction_Fn[i] = NULL;
+        else
+            Direction_Fn[i] = src.Direction_Fn[i]->Clone();
+
+    }
+
     return *this;
 }
 
@@ -368,6 +392,11 @@ Camera::Camera(const Camera& src)
     Tnormal = NULL;
     Trans = NULL;
     Bokeh = NULL;
+    for (unsigned int i = 0; i < 3; ++i)
+    {
+        Location_Fn[i]  = NULL;
+        Direction_Fn[i] = NULL;
+    }
     operator=(src);
 }
 
@@ -405,6 +434,13 @@ Camera::~Camera()
     for (std::vector<ObjectPtr>::iterator it = Meshes.begin(); it != Meshes.end(); it++)
         Destroy_Object(*it);
     Meshes.clear();
+    for (unsigned int i = 0; i < 3; ++i)
+    {
+        if (Location_Fn[i] != NULL)
+            delete Location_Fn[i];
+        if (Direction_Fn[i] != NULL)
+            delete Direction_Fn[i];
+    }
 }
 
 }

source/core/scene/camera.h

@@ -63,6 +63,7 @@ namespace pov
 #define CYL_4_CAMERA           10
 #define SPHERICAL_CAMERA       11
 #define MESH_CAMERA            12
+#define USER_DEFINED_CAMERA    13
 
 /*****************************************************************************
 * Global typedefs
@@ -90,6 +91,8 @@ class Camera
     TNORMAL *Tnormal;               // Primary ray pertubation.
     TRANSFORM *Trans;               // Used only to record the user's input
     PIGMENT *Bokeh;                 // Pigment to use for the bokeh
+    GenericScalarFunctionPtr Location_Fn[3];  // [USER_DEFINED_CAMERA] Set of functions defining the ray's origin for each screen position.
+    GenericScalarFunctionPtr Direction_Fn[3]; // [USER_DEFINED_CAMERA] Set of functions defining the ray's direction for each screen position.
 
     // the following declarations are used for the mesh camera
     unsigned int Face_Distribution_Method;  // how to associate a pixel to a face within a mesh