first commit

ios/include/filament/Exposure.h

@@ -0,0 +1,129 @@
+/*
+ * Copyright (C) 2015 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+//! \file
+
+#ifndef TNT_FILAMENT_EXPOSURE_H
+#define TNT_FILAMENT_EXPOSURE_H
+
+#include <utils/compiler.h>
+
+namespace filament {
+
+class Camera;
+
+/**
+ * A series of utilities to compute exposure, exposure value at ISO 100 (EV100),
+ * luminance and illuminance using a physically-based camera model.
+ */
+namespace Exposure {
+
+/**
+ * Returns the exposure value (EV at ISO 100) of the specified camera.
+ */
+UTILS_PUBLIC
+float ev100(const Camera& camera) noexcept;
+
+/**
+ * Returns the exposure value (EV at ISO 100) of the specified exposure parameters.
+ */
+UTILS_PUBLIC
+float ev100(float aperture, float shutterSpeed, float sensitivity) noexcept;
+
+/**
+ * Returns the exposure value (EV at ISO 100) for the given average luminance (in @f$ \frac{cd}{m^2} @f$).
+ */
+UTILS_PUBLIC
+float ev100FromLuminance(float luminance) noexcept;
+
+/**
+* Returns the exposure value (EV at ISO 100) for the given illuminance (in lux).
+*/
+UTILS_PUBLIC
+float ev100FromIlluminance(float illuminance) noexcept;
+
+/**
+ * Returns the photometric exposure for the specified camera.
+ */
+UTILS_PUBLIC
+float exposure(const Camera& camera) noexcept;
+
+/**
+ * Returns the photometric exposure for the specified exposure parameters.
+ * This function is equivalent to calling `exposure(ev100(aperture, shutterSpeed, sensitivity))`
+ * but is slightly faster and offers higher precision.
+ */
+UTILS_PUBLIC
+float exposure(float aperture, float shutterSpeed, float sensitivity) noexcept;
+
+/**
+ * Returns the photometric exposure for the given EV100.
+ */
+UTILS_PUBLIC
+float exposure(float ev100) noexcept;
+
+/**
+ * Returns the incident luminance in @f$ \frac{cd}{m^2} @f$ for the specified camera acting as a spot meter.
+ */
+UTILS_PUBLIC
+float luminance(const Camera& camera) noexcept;
+
+/**
+ * Returns the incident luminance in @f$ \frac{cd}{m^2} @f$ for the specified exposure parameters of
+ * a camera acting as a spot meter.
+ * This function is equivalent to calling `luminance(ev100(aperture, shutterSpeed, sensitivity))`
+ * but is slightly faster and offers higher precision.
+ */
+UTILS_PUBLIC
+float luminance(float aperture, float shutterSpeed, float sensitivity) noexcept;
+
+/**
+ * Converts the specified EV100 to luminance in @f$ \frac{cd}{m^2} @f$.
+ * EV100 is not a measure of luminance, but an EV100 can be used to denote a
+ * luminance for which a camera would use said EV100 to obtain the nominally
+ * correct exposure
+ */
+UTILS_PUBLIC
+float luminance(float ev100) noexcept;
+
+/**
+ * Returns the illuminance in lux for the specified camera acting as an incident light meter.
+ */
+UTILS_PUBLIC
+float illuminance(const Camera& camera) noexcept;
+
+/**
+ * Returns the illuminance in lux for the specified exposure parameters of
+ * a camera acting as an incident light meter.
+ * This function is equivalent to calling `illuminance(ev100(aperture, shutterSpeed, sensitivity))`
+ * but is slightly faster and offers higher precision.
+ */
+UTILS_PUBLIC
+float illuminance(float aperture, float shutterSpeed, float sensitivity) noexcept;
+
+/**
+ * Converts the specified EV100 to illuminance in lux.
+ * EV100 is not a measure of illuminance, but an EV100 can be used to denote an
+ * illuminance for which a camera would use said EV100 to obtain the nominally
+ * correct exposure.
+ */
+UTILS_PUBLIC
+float illuminance(float ev100) noexcept;
+
+} // namespace exposure
+} // namespace filament
+
+#endif // TNT_FILAMENT_EXPOSURE_H