Add exposure controls to UsdGeomCamera

pxr/imaging/hd/camera.cpp

@@ -255,6 +255,41 @@ HdCamera::Sync(HdSceneDelegate * sceneDelegate,
             _exposure = vExposure.Get<float>();
         }
 
+        const VtValue vExposureCompensation =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureCompensation);
+        if (!vExposureCompensation.IsEmpty()) {
+            _exposureCompensation = vExposureCompensation.Get<float>();
+        }
+
+        const VtValue vExposureTime =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureTime);
+        if (!vExposureTime.IsEmpty()) {
+            _exposureTime = vExposureTime.Get<float>();
+        }
+
+        const VtValue vExposureIso =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureIso);
+        if (!vExposureIso.IsEmpty()) {
+            _exposureIso = vExposureIso.Get<float>();
+        }
+
+        const VtValue vExposureFNumber =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureFNumber);
+        if (!vExposureFNumber.IsEmpty()) {
+            _exposureFNumber = vExposureFNumber.Get<float>();
+        }
+
+        const VtValue vExposureResponsivity =
+            sceneDelegate->GetCameraParamValue(
+                id, HdCameraTokens->exposureResponsivity);
+        if (!vExposureResponsivity.IsEmpty()) {
+            _exposureResponsivity = vExposureResponsivity.Get<float>();
+        }
+
         const VtValue vLensDistortionType =
             sceneDelegate->GetCameraParamValue(
                 id, HdCameraTokens->lensDistortionType);

pxr/imaging/hd/camera.h

@@ -74,6 +74,11 @@ PXR_NAMESPACE_OPEN_SCOPE
     (shutterOpen)                                                 \
     (shutterClose)                                                \
     (exposure)                                                    \
+    (exposureTime)                                                \
+    (exposureIso)                                                 \
+    (exposureFNumber)                                             \
+    (exposureResponsivity)                                        \
+    (exposureCompensation)                                        \
                                                                   \
     /* how to match window with different aspect */               \
     (windowPolicy)                                                \
@@ -330,10 +335,17 @@ class HdCamera : public HdSprim
     float                   _splitDiopterWidth2;
     float                   _splitDiopterFocusDistance2;
 
-    // shutter/lighting
+    // shutter
     double                  _shutterOpen;
     double                  _shutterClose;
+
+    // exposure
     float                   _exposure;
+    float                   _exposureCompensation;
+    float                   _exposureTime;
+    float                   _exposureIso;
+    float                   _exposureFNumber;
+    float                   _exposureResponsivity;
 
     // lens distortion
     TfToken                 _lensDistortionType;

pxr/usd/usdGeom/camera.cpp

@@ -341,6 +341,74 @@ UsdGeomCamera::CreateExposureAttr(VtValue const &defaultValue, bool writeSparsel
                        writeSparsely);
 }
 
+UsdAttribute
+UsdGeomCamera::GetExposureIsoAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureIso);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureIsoAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureIso,
+                       SdfValueTypeNames->Float,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
+UsdAttribute
+UsdGeomCamera::GetExposureTimeAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureTime);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureTimeAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureTime,
+                       SdfValueTypeNames->Float,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
+UsdAttribute
+UsdGeomCamera::GetExposureFNumberAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureFNumber);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureFNumberAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureFNumber,
+                       SdfValueTypeNames->Float,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
+UsdAttribute
+UsdGeomCamera::GetExposureResponsivityAttr() const
+{
+    return GetPrim().GetAttribute(UsdGeomTokens->exposureResponsivity);
+}
+
+UsdAttribute
+UsdGeomCamera::CreateExposureResponsivityAttr(VtValue const &defaultValue, bool writeSparsely) const
+{
+    return UsdSchemaBase::_CreateAttr(UsdGeomTokens->exposureResponsivity,
+                       SdfValueTypeNames->Float,
+                       /* custom = */ false,
+                       SdfVariabilityVarying,
+                       defaultValue,
+                       writeSparsely);
+}
+
 namespace {
 static inline TfTokenVector
 _ConcatenateAttributeNames(const TfTokenVector& left,const TfTokenVector& right)
@@ -372,6 +440,10 @@ UsdGeomCamera::GetSchemaAttributeNames(bool includeInherited)
         UsdGeomTokens->shutterOpen,
         UsdGeomTokens->shutterClose,
         UsdGeomTokens->exposure,
+        UsdGeomTokens->exposureIso,
+        UsdGeomTokens->exposureTime,
+        UsdGeomTokens->exposureFNumber,
+        UsdGeomTokens->exposureResponsivity,
     };
     static TfTokenVector allNames =
         _ConcatenateAttributeNames(
@@ -581,4 +653,23 @@ UsdGeomCamera::SetFromCamera(const GfCamera &camera, const UsdTimeCode &time)
     GetFocusDistanceAttr().Set(camera.GetFocusDistance(), time);
 }
 
+float
+UsdGeomCamera::GetExposureScale(UsdTimeCode time) const 
+{   
+    float exposureTime = 1.0f;
+    float exposureIso = 100.0f;
+    float exposureFNumber = 1.0f;
+    float exposureResponsivity = 1.0f;
+    float exposureCompensation = 0.0f;
+
+    GetExposureTimeAttr().Get(&exposureTime, time);
+    GetExposureIsoAttr().Get(&exposureIso, time);
+    GetExposureFNumberAttr().Get(&exposureFNumber, time);
+    GetExposureResponsivityAttr().Get(&exposureResponsivity, time);
+    GetExposureAttr().Get(&exposureCompensation, time);
+
+    return (exposureTime * exposureIso * powf(2.0f, exposureCompensation) * 
+            exposureResponsivity) / (100.0f * exposureFNumber * exposureFNumber);
+}
+
 PXR_NAMESPACE_CLOSE_SCOPE

pxr/usd/usdGeom/camera.h

@@ -394,7 +394,7 @@ class UsdGeomCamera : public UsdGeomXformable
     // --------------------------------------------------------------------- //
     // FSTOP 
     // --------------------------------------------------------------------- //
-    /// Lens aperture. Defaults to 0.0, which turns off focusing.
+    /// Lens aperture. Defaults to 0.0, which turns off depth of field effects.
     ///
     /// | ||
     /// | -- | -- |
@@ -491,7 +491,7 @@ class UsdGeomCamera : public UsdGeomXformable
     /// Frame relative shutter close time, analogous comments from
     /// shutter:open apply. A value greater or equal to shutter:open
     /// should be authored, otherwise there is no exposure and a
-    /// renderer should produce a black image.
+    /// renderer should produce a black image. Used for motion blur.
     ///
     /// | ||
     /// | -- | -- |
@@ -513,7 +513,7 @@ class UsdGeomCamera : public UsdGeomXformable
     // --------------------------------------------------------------------- //
     // EXPOSURE 
     // --------------------------------------------------------------------- //
-    /// Exposure adjustment, as a log base-2 value.  The default
+    /// Exposure compensation, as a log base-2 value.  The default
     /// of 0.0 has no effect.  A value of 1.0 will double the
     /// image-plane intensities in a rendered image; a value of
     /// -1.0 will halve them.
@@ -534,6 +534,99 @@ class UsdGeomCamera : public UsdGeomXformable
     USDGEOM_API
     UsdAttribute CreateExposureAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
 
+public:
+    // --------------------------------------------------------------------- //
+    // EXPOSUREISO 
+    // --------------------------------------------------------------------- //
+    /// The speed rating of the sensor or film when calculating exposure.
+    /// Higher numbers give a brighter image, lower numbers darker.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:iso = 100` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureIsoAttr() const;
+
+    /// See GetExposureIsoAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    USDGEOM_API
+    UsdAttribute CreateExposureIsoAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
+public:
+    // --------------------------------------------------------------------- //
+    // EXPOSURETIME 
+    // --------------------------------------------------------------------- //
+    /// Time in seconds that the sensor is exposed to light when calculating exposure.
+    /// Longer exposure times create a brighter image, shorter times darker.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:time = 1` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureTimeAttr() const;
+
+    /// See GetExposureTimeAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    USDGEOM_API
+    UsdAttribute CreateExposureTimeAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
+public:
+    // --------------------------------------------------------------------- //
+    // EXPOSUREFNUMBER 
+    // --------------------------------------------------------------------- //
+    /// f-number of the aperture when calculating exposure. Smaller numbers
+    /// create a brighter image, larger numbers darker.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:fNumber = 1` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureFNumberAttr() const;
+
+    /// See GetExposureFNumberAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    USDGEOM_API
+    UsdAttribute CreateExposureFNumberAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
+public:
+    // --------------------------------------------------------------------- //
+    // EXPOSURERESPONSIVITY 
+    // --------------------------------------------------------------------- //
+    /// Scalar multiplier representing overall responsivity of the 
+    /// sensor system to light when calculating exposure. Intended to be
+    /// used as a per camera/lens system measured scaling value.
+    ///
+    /// | ||
+    /// | -- | -- |
+    /// | Declaration | `float exposure:responsivity = 1` |
+    /// | C++ Type | float |
+    /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float |
+    USDGEOM_API
+    UsdAttribute GetExposureResponsivityAttr() const;
+
+    /// See GetExposureResponsivityAttr(), and also 
+    /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
+    /// If specified, author \p defaultValue as the attribute's default,
+    /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
+    /// the default for \p writeSparsely is \c false.
+    USDGEOM_API
+    UsdAttribute CreateExposureResponsivityAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
+
 public:
     // ===================================================================== //
     // Feel free to add custom code below this line, it will be preserved by 
@@ -574,6 +667,18 @@ class UsdGeomCamera : public UsdGeomXformable
     ///
     USDGEOM_API
     void SetFromCamera(const GfCamera &camera, const UsdTimeCode &time);
+
+    /// Computes the imaging ratio, i.e. the ratio between incident luminance and
+    /// photometric exposure (in lux-seconds), given the exposure, exposure:iso,
+    /// exposure:fnumber, exposure:time and exposure:responsivity attributes.
+    ///
+    /// This is expected to be applied as a multiplier to the brightness of the 
+    /// image generated by the renderer, and given physically meaningful lighting
+    /// values in the scene, allows the exposure controls on UsdGeomCamera to behave
+    /// like those of a real camera.
+    ///
+    USDGEOM_API
+    float GetExposureScale(UsdTimeCode time=UsdTimeCode::Default()) const;
 };
 
 PXR_NAMESPACE_CLOSE_SCOPE

pxr/usd/usdGeom/generatedSchema.usda

@@ -4210,11 +4210,28 @@ class Camera "Camera" (
                  ."""
     )
     float exposure = 0 (
-        doc = """Exposure adjustment, as a log base-2 value.  The default
+        doc = """Exposure compensation, as a log base-2 value.  The default
                  of 0.0 has no effect.  A value of 1.0 will double the
                  image-plane intensities in a rendered image; a value of
                  -1.0 will halve them."""
     )
+    float exposure:fNumber = 1 (
+        doc = """f-number of the aperture when calculating exposure. Smaller numbers
+                 create a brighter image, larger numbers darker."""
+    )
+    float exposure:iso = 100 (
+        doc = """The speed rating of the sensor or film when calculating exposure.
+                 Higher numbers give a brighter image, lower numbers darker."""
+    )
+    float exposure:responsivity = 1 (
+        doc = """Scalar multiplier representing overall responsivity of the 
+                 sensor system to light when calculating exposure. Intended to be
+                 used as a per camera/lens system measured scaling value."""
+    )
+    float exposure:time = 1 (
+        doc = """Time in seconds that the sensor is exposed to light when calculating exposure.
+                 Longer exposure times create a brighter image, shorter times darker."""
+    )
     float focalLength = 50 (
         doc = """Perspective focal length in tenths of a scene unit; see 
                  ."""
@@ -4224,7 +4241,7 @@ class Camera "Camera" (
                  ."""
     )
     float fStop = 0 (
-        doc = "Lens aperture. Defaults to 0.0, which turns off focusing."
+        doc = "Lens aperture. Defaults to 0.0, which turns off depth of field effects."
     )
     float horizontalAperture = 20.955 (
         doc = """Horizontal aperture in tenths of a scene unit; see 
@@ -4273,7 +4290,7 @@ class Camera "Camera" (
         doc = """Frame relative shutter close time, analogous comments from
                  shutter:open apply. A value greater or equal to shutter:open
                  should be authored, otherwise there is no exposure and a
-                 renderer should produce a black image."""
+                 renderer should produce a black image. Used for motion blur."""
     )
     double shutter:open = 0 (
         doc = """Frame relative shutter open time in UsdTimeCode units (negative