maobo/cup_edit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Nick Fisher
2021-09-15 20:07:11 +08:00
commit a0f877be48
292 changed files with 100157 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

198
ios/include/filament/Box.h Normal file
View File

@@ -0,0 +1,198 @@
/*
* 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_BOX_H
#define TNT_FILAMENT_BOX_H
#include <utils/compiler.h>
#include <limits>
#include <math/mat4.h>
#include <math/vec3.h>
namespace filament {
/**
* An axis aligned 3D box represented by its center and half-extent.
*/
class UTILS_PUBLIC Box {
public:
/** Center of the 3D box */
math::float3 center = {};
/** Half extent from the center on all 3 axis */
math::float3 halfExtent = {};
/**
* Whether the box is empty, i.e.: it's volume is null.
* @return true if the volume of the box is null
*/
constexpr bool isEmpty() const noexcept {
return length2(halfExtent) == 0;
}
/**
* Computes the lowest coordinates corner of the box.
* @return center - halfExtent
*/
constexpr math::float3 getMin() const noexcept {
return center - halfExtent;
}
/**
* Computes the largest coordinates corner of the box.
* @return center + halfExtent
*/
constexpr math::float3 getMax() const noexcept {
return center + halfExtent;
}
/**
* Initializes the 3D box from its min / max coordinates on each axis
* @param min lowest coordinates corner of the box
* @param max largest coordinates corner of the box
* @return This bounding box
*/
Box& set(const math::float3& min, const math::float3& max) noexcept {
// float3 ctor needed for visual studio
center = (max + min) * math::float3(0.5f);
halfExtent = (max - min) * math::float3(0.5f);
return *this;
}
/**
* Computes the bounding box of the union of two boxes
* @param box The box to be combined with
* @return The bounding box of the union of *this and box
*/
Box& unionSelf(const Box& box) noexcept {
set(min(getMin(), box.getMin()), max(getMax(), box.getMax()));
return *this;
}
/**
* Translates the box *to* a given center position
* @param tr position to translate the box to
* @return A box centered in \p tr with the same extent than *this
*/
constexpr Box translateTo(const math::float3& tr) const noexcept {
return Box{ tr, halfExtent };
}
/**
* Computes the smallest bounding sphere of the box.
* @return The smallest sphere defined by its center (.xyz) and radius (.w) that contains *this
*/
math::float4 getBoundingSphere() const noexcept {
return { center, length(halfExtent) };
}
/**
* Computes the bounding box of a box transformed by a rigid transform
* @param box the box to transform
* @param m a 4x4 matrix that must be a rigid transform
* @return the bounding box of the transformed box.
* Result is undefined if \p m is not a rigid transform
*/
friend Box rigidTransform(Box const& box, const math::mat4f& m) noexcept;
/**
* Computes the bounding box of a box transformed by a rigid transform
* @param box the box to transform
* @param m a 3x3 matrix that must be a rigid transform
* @return the bounding box of the transformed box.
* Result is undefined if \p m is not a rigid transform
*/
friend Box rigidTransform(Box const& box, const math::mat3f& m) noexcept;
};
/**
* An axis aligned box represented by its min and max coordinates
*/
struct UTILS_PUBLIC Aabb {
/** min coordinates */
math::float3 min = std::numeric_limits<float>::max();
/** max coordinates */
math::float3 max = std::numeric_limits<float>::lowest();
/**
* Computes the center of the box.
* @return (max + min)/2
*/
math::float3 center() const noexcept {
// float3 ctor needed for visual studio
return (max + min) * math::float3(0.5f);
}
/**
* Computes the half-extent of the box.
* @return (max - min)/2
*/
math::float3 extent() const noexcept {
// float3 ctor needed for visual studio
return (max - min) * math::float3(0.5f);
}
/**
* Whether the box is empty, i.e.: it's volume is null or negative.
* @return true if min >= max, i.e: the volume of the box is null or negative
*/
bool isEmpty() const noexcept {
return any(greaterThanEqual(min, max));
}
struct Corners {
using value_type = math::float3;
value_type const* begin() const { return vertices; }
value_type const* end() const { return vertices + 8; }
value_type * begin() { return vertices; }
value_type * end() { return vertices + 8; }
value_type const* data() const { return vertices; }
value_type * data() { return vertices; }
size_t size() const { return 8; }
value_type vertices[8];
};
/**
* Returns the 8 corner vertices of the AABB.
*/
Corners getCorners() const;
/**
* Returns whether the box contains a given point.
*
* @param p the point to test
* @return the maximum signed distance to the box. Negative if p is in the box
*/
float contains(math::float3 p) const noexcept;
/**
* Applies an affine transformation to the AABB.
*
* @param m the 4x4 transformation to apply
* @return the transformed box
*/
Aabb transform(const math::mat4f& m) const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_BOX_H

117
ios/include/filament/BufferObject.h Normal file
View File

@@ -0,0 +1,117 @@
/*
* Copyright (C) 2021 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_BUFFEROBJECT_H
#define TNT_FILAMENT_BUFFEROBJECT_H
#include <filament/FilamentAPI.h>
#include <backend/DriverEnums.h>
#include <backend/BufferDescriptor.h>
#include <utils/compiler.h>
namespace filament {
class FBufferObject;
class Engine;
/**
* A generic GPU buffer containing data.
*
* Usage of this BufferObject is optional. For simple use cases it is not necessary. It is useful
* only when you need to share data between multiple VertexBuffer instances. It also allows you to
* efficiently swap-out the buffers in VertexBuffer.
*
* NOTE: For now this is only used for vertex data, but in the future we may use it for other things
* (e.g. compute).
*
* @see VertexBuffer
*/
class UTILS_PUBLIC BufferObject : public FilamentAPI {
struct BuilderDetails;
public:
using BufferDescriptor = backend::BufferDescriptor;
using BindingType = backend::BufferObjectBinding;
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Size of the buffer in bytes.
* @param byteCount Maximum number of bytes the BufferObject can hold.
* @return A reference to this Builder for chaining calls.
*/
Builder& size(uint32_t byteCount) noexcept;
/**
* The binding type for this buffer object. (defaults to VERTEX)
* @param BindingType Distinguishes between SSBO, VBO, etc. For now this must be VERTEX.
* @return A reference to this Builder for chaining calls.
*/
Builder& bindingType(BindingType bindingType) noexcept;
/**
* Creates the BufferObject and returns a pointer to it. After creation, the buffer
* object is uninitialized. Use BufferObject::setBuffer() to initialize it.
*
* @param engine Reference to the filament::Engine to associate this BufferObject with.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*
* @see IndexBuffer::setBuffer
*/
BufferObject* build(Engine& engine);
private:
friend class FBufferObject;
};
/**
* Asynchronously copy-initializes a region of this BufferObject from the data provided.
*
* @param engine Reference to the filament::Engine associated with this BufferObject.
* @param buffer A BufferDescriptor representing the data used to initialize the BufferObject.
* @param byteOffset Offset in bytes into the BufferObject
*/
void setBuffer(Engine& engine, BufferDescriptor&& buffer, uint32_t byteOffset = 0);
/**
* Returns the size of this BufferObject in elements.
* @return The maximum capacity of the BufferObject.
*/
size_t getByteCount() const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_BUFFEROBJECT_H

516
ios/include/filament/Camera.h Normal file
View File

@@ -0,0 +1,516 @@
/*
* 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_CAMERA_H
#define TNT_FILAMENT_CAMERA_H
#include <filament/FilamentAPI.h>
#include <utils/compiler.h>
#include <math/mathfwd.h>
#include <math/vec2.h>
#include <math/vec4.h>
namespace utils {
class Entity;
} // namespace utils
namespace filament {
/**
* Camera represents the eye through which the scene is viewed.
*
* A Camera has a position and orientation and controls the projection and exposure parameters.
*
* Creation and destruction
* ========================
*
* In Filament, Camera is a component that must be associated with an entity. To do so,
* use Engine::createCamera(Entity). A Camera component is destroyed using
* Engine::destroyCameraComponent(Entity).
*
* ~~~~~~~~~~~{.cpp}
* filament::Engine* engine = filament::Engine::create();
*
* utils::Entity myCameraEntity = utils::EntityManager::get().create();
* filament::Camera* myCamera = engine->createCamera(myCameraEntity);
* myCamera->setProjection(45, 16.0/9.0, 0.1, 1.0);
* myCamera->lookAt({0, 1.60, 1}, {0, 0, 0});
* engine->destroyCameraComponent(myCamera);
* ~~~~~~~~~~~
*
*
* Coordinate system
* =================
*
* The camera coordinate system defines the *view space*. The camera points towards its -z axis
* and is oriented such that its top side is in the direction of +y, and its right side in the
* direction of +x.
*
* @note
* Since the *near* and *far* planes are defined by the distance from the camera,
* their respective coordinates are -\p distance(near) and -\p distance(far).
*
* Clipping planes
* ===============
*
* The camera defines six *clipping planes* which together create a *clipping volume*. The
* geometry outside this volume is clipped.
*
* The clipping volume can either be a box or a frustum depending on which projection is used,
* respectively Projection.ORTHO or Projection.PERSPECTIVE. The six planes are specified either
* directly or indirectly using setProjection().
*
* The six planes are:
* - left
* - right
* - bottom
* - top
* - near
* - far
*
* @note
* To increase the depth-buffer precision, the *far* clipping plane is always assumed to be at
* infinity for rendering. That is, it is not used to clip geometry during rendering.
* However, it is used during the culling phase (objects entirely behind the *far*
* plane are culled).
*
*
* Choosing the *near* plane distance
* ==================================
*
* The *near* plane distance greatly affects the depth-buffer resolution.
*
* Example: Precision at 1m, 10m, 100m and 1Km for various near distances assuming a 32-bit float
* depth-buffer
*
* near (m) | 1 m | 10 m | 100 m | 1 Km
* -----------:|:------:|:-------:|:--------:|:--------:
* 0.001 | 7.2e-5 | 0.0043 | 0.4624 | 48.58
* 0.01 | 6.9e-6 | 0.0001 | 0.0430 | 4.62
* 0.1 | 3.6e-7 | 7.0e-5 | 0.0072 | 0.43
* 1.0 | 0 | 3.8e-6 | 0.0007 | 0.07
*
*
* As can be seen in the table above, the depth-buffer precision drops rapidly with the
* distance to the camera.
* Make sure to pick the highest *near* plane distance possible.
*
*
* Exposure
* ========
*
* The Camera is also used to set the scene's exposure, just like with a real camera. The lights
* intensity and the Camera exposure interact to produce the final scene's brightness.
*
*
*
* \see Frustum, View
*/
class UTILS_PUBLIC Camera : public FilamentAPI {
public:
//! Denotes the projection type used by this camera. \see setProjection
enum class Projection : int {
PERSPECTIVE, //!< perspective projection, objects get smaller as they are farther
ORTHO //!< orthonormal projection, preserves distances
};
//! Denotes a field-of-view direction. \see setProjection
enum class Fov : int {
VERTICAL, //!< the field-of-view angle is defined on the vertical axis
HORIZONTAL //!< the field-of-view angle is defined on the horizontal axis
};
/** Sets the projection matrix from a frustum defined by six planes.
*
* @param projection type of #Projection to use.
*
* @param left distance in world units from the camera to the left plane,
* at the near plane.
* Precondition: \p left != \p right.
*
* @param right distance in world units from the camera to the right plane,
* at the near plane.
* Precondition: \p left != \p right.
*
* @param bottom distance in world units from the camera to the bottom plane,
* at the near plane.
* Precondition: \p bottom != \p top.
*
* @param top distance in world units from the camera to the top plane,
* at the near plane.
* Precondition: \p left != \p right.
*
* @param near distance in world units from the camera to the near plane. The near plane's
* position in view space is z = -\p near.
* Precondition: \p near > 0 for PROJECTION::PERSPECTIVE or
* \p near != far for PROJECTION::ORTHO
*
* @param far distance in world units from the camera to the far plane. The far plane's
* position in view space is z = -\p far.
* Precondition: \p far > near for PROJECTION::PERSPECTIVE or
* \p far != near for PROJECTION::ORTHO
*
* @attention these parameters are silently modified to meet the preconditions above.
*
* @see Projection, Frustum
*/
void setProjection(Projection projection,
double left, double right,
double bottom, double top,
double near, double far) noexcept;
/** Sets the projection matrix from the field-of-view.
*
* @param fovInDegrees full field-of-view in degrees. 0 < \p fov < 180.
* @param aspect aspect ratio \f$ \frac{width}{height} \f$. \p aspect > 0.
* @param near distance in world units from the camera to the near plane. \p near > 0.
* @param far distance in world units from the camera to the far plane. \p far > \p near.
* @param direction direction of the \p fovInDegrees parameter.
*
* @see Fov.
*/
void setProjection(double fovInDegrees, double aspect, double near, double far,
Fov direction = Fov::VERTICAL) noexcept;
/** Sets the projection matrix from the focal length.
*
* @param focalLengthInMillimeters lens's focal length in millimeters. \p focalLength > 0.
* @param aspect aspect ratio \f$ \frac{width}{height} \f$. \p aspect > 0.
* @param near distance in world units from the camera to the near plane. \p near > 0.
* @param far distance in world units from the camera to the far plane. \p far > \p near.
*/
void setLensProjection(double focalLengthInMillimeters,
double aspect, double near, double far) noexcept;
/** Sets a custom projection matrix.
*
* The projection matrix must be of one of the following form:
* a 0 tx 0 a 0 0 tx
* 0 b ty 0 0 b 0 ty
* 0 0 tz c 0 0 c tz
* 0 0 -1 0 0 0 0 1
*
* The projection matrix must define an NDC system that must match the OpenGL convention,
* that is all 3 axis are mapped to [-1, 1].
*
* @param projection custom projection matrix used for rendering and culling
* @param near distance in world units from the camera to the near plane. \p near > 0.
* @param far distance in world units from the camera to the far plane. \p far > \p near.
*/
void setCustomProjection(math::mat4 const& projection, double near, double far) noexcept;
/** Sets the projection matrix.
*
* The projection matrices must be of one of the following form:
* a 0 tx 0 a 0 0 tx
* 0 b ty 0 0 b 0 ty
* 0 0 tz c 0 0 c tz
* 0 0 -1 0 0 0 0 1
*
* The projection matrices must define an NDC system that must match the OpenGL convention,
* that is all 3 axis are mapped to [-1, 1].
*
* @param projection custom projection matrix used for rendering
* @param projectionForCulling custom projection matrix used for culling
* @param near distance in world units from the camera to the near plane. \p near > 0.
* @param far distance in world units from the camera to the far plane. \p far > \p near.
*/
void setCustomProjection(math::mat4 const& projection, math::mat4 const& projectionForCulling,
double near, double far) noexcept;
/** Sets an additional matrix that scales the projection matrix.
*
* This is useful to adjust the aspect ratio of the camera independent from its projection.
* First, pass an aspect of 1.0 to setProjection. Then set the scaling with the desired aspect
* ratio:
*
* const double aspect = width / height;
*
* // with Fov::HORIZONTAL passed to setProjection:
* camera->setScaling(double4 {1.0, aspect});
*
* // with Fov::VERTICAL passed to setProjection:
* camera->setScaling(double4 {1.0 / aspect, 1.0});
*
*
* By default, this is an identity matrix.
*
* @param scaling diagonal of the 2x2 scaling matrix to be applied after the projection matrix.
*
* @see setProjection, setLensProjection, setCustomProjection
*/
void setScaling(math::double2 scaling) noexcept;
/**
* Sets an additional matrix that shifts the projection matrix.
* By default, this is an identity matrix.
*
* @param shift x and y translation added to the projection matrix, specified in NDC
* coordinates, that is, if the translation must be specified in pixels,
* shift must be scaled by 1.0 / { viewport.width, viewport.height }.
*
* @see setProjection, setLensProjection, setCustomProjection
*/
void setShift(math::double2 shift) noexcept;
/** Returns the scaling amount used to scale the projection matrix.
*
* @return the diagonal of the scaling matrix applied after the projection matrix.
*
* @see setScaling
*/
math::double4 getScaling() const noexcept;
/** Returns the shift amount used to translate the projection matrix.
*
* @return the 2D translation x and y offsets applied after the projection matrix.
*
* @see setShift
*/
math::double2 getShift() const noexcept;
/** Returns the projection matrix used for rendering.
*
* The projection matrix used for rendering always has its far plane set to infinity. This
* is why it may differ from the matrix set through setProjection() or setLensProjection().
*
* @return The projection matrix used for rendering
*
* @see setProjection, setLensProjection, setCustomProjection, getCullingProjectionMatrix
*/
math::mat4 getProjectionMatrix() const noexcept;
/** Returns the projection matrix used for culling (far plane is finite).
*
* @return The projection matrix set by setProjection or setLensProjection.
*
* @see setProjection, setLensProjection, getProjectionMatrix
*/
math::mat4 getCullingProjectionMatrix() const noexcept;
//! Returns the frustum's near plane
float getNear() const noexcept;
//! Returns the frustum's far plane used for culling
float getCullingFar() const noexcept;
/** Sets the camera's view matrix.
*
* Helper method to set the camera's entity transform component.
* It has the same effect as calling:
*
* ~~~~~~~~~~~{.cpp}
* engine.getTransformManager().setTransform(
* engine.getTransformManager().getInstance(camera->getEntity()), view);
* ~~~~~~~~~~~
*
* @param view The camera position and orientation provided as a rigid transform matrix.
*
* @note The Camera "looks" towards its -z axis
*
* @warning \p view must be a rigid transform
*/
void setModelMatrix(const math::mat4& view) noexcept;
void setModelMatrix(const math::mat4f& view) noexcept; //!< \overload
/** Sets the camera's view matrix
*
* @param eye The position of the camera in world space.
* @param center The point in world space the camera is looking at.
* @param up A unit vector denoting the camera's "up" direction.
*/
void lookAt(const math::float3& eye,
const math::float3& center,
const math::float3& up) noexcept;
/** Sets the camera's view matrix, assuming up is along the y axis
*
* @param eye The position of the camera in world space.
* @param center The point in world space the camera is looking at.
*/
void lookAt(const math::float3& eye,
const math::float3& center) noexcept;
/** Returns the camera's model matrix
*
* Helper method to return the camera's entity transform component.
* It has the same effect as calling:
*
* ~~~~~~~~~~~{.cpp}
* engine.getTransformManager().getWorldTransform(
* engine.getTransformManager().getInstance(camera->getEntity()));
* ~~~~~~~~~~~
*
* @return The camera's pose in world space as a rigid transform. Parent transforms, if any,
* are taken into account.
*/
math::mat4 getModelMatrix() const noexcept;
//! Returns the camera's view matrix (inverse of the model matrix)
math::mat4 getViewMatrix() const noexcept;
//! Returns the camera's position in world space
math::float3 getPosition() const noexcept;
//! Returns the camera's normalized left vector
math::float3 getLeftVector() const noexcept;
//! Returns the camera's normalized up vector
math::float3 getUpVector() const noexcept;
//! Returns the camera's forward vector
math::float3 getForwardVector() const noexcept;
//! Returns the camera's field of view in degrees
float getFieldOfViewInDegrees(Fov direction) const noexcept;
//! Returns a Frustum object in world space
class Frustum getFrustum() const noexcept;
//! Returns the entity representing this camera
utils::Entity getEntity() const noexcept;
/** Sets this camera's exposure (default is f/16, 1/125s, 100 ISO)
*
* The exposure ultimately controls the scene's brightness, just like with a real camera.
* The default values provide adequate exposure for a camera placed outdoors on a sunny day
* with the sun at the zenith.
*
* @param aperture Aperture in f-stops, clamped between 0.5 and 64.
* A lower \p aperture value *increases* the exposure, leading to
* a brighter scene. Realistic values are between 0.95 and 32.
*
* @param shutterSpeed Shutter speed in seconds, clamped between 1/25,000 and 60.
* A lower shutter speed increases the exposure. Realistic values are
* between 1/8000 and 30.
*
* @param sensitivity Sensitivity in ISO, clamped between 10 and 204,800.
* A higher \p sensitivity increases the exposure. Realistic values are
* between 50 and 25600.
*
* @note
* With the default parameters, the scene must contain at least one Light of intensity
* similar to the sun (e.g.: a 100,000 lux directional light).
*
* @see LightManager, Exposure
*/
void setExposure(float aperture, float shutterSpeed, float sensitivity) noexcept;
/** Sets this camera's exposure directly. Calling this method will set the aperture
* to 1.0, the shutter speed to 1.2 and the sensitivity will be computed to match
* the requested exposure (for a desired exposure of 1.0, the sensitivity will be
* set to 100 ISO).
*
* This method is useful when trying to match the lighting of other engines or tools.
* Many engines/tools use unit-less light intensities, which can be matched by setting
* the exposure manually. This can be typically achieved by setting the exposure to
* 1.0.
*/
void setExposure(float exposure) noexcept {
setExposure(1.0f, 1.2f, 100.0f * (1.0f / exposure));
}
//! returns this camera's aperture in f-stops
float getAperture() const noexcept;
//! returns this camera's shutter speed in seconds
float getShutterSpeed() const noexcept;
//! returns this camera's sensitivity in ISO
float getSensitivity() const noexcept;
//! returns the focal length in meters [m] for a 35mm camera
double getFocalLength() const noexcept;
/**
* Sets the camera focus distance. This is used by the Depth-of-field PostProcessing effect.
* @param distance Distance from the camera to the plane of focus in world units.
* Must be positive and larger than the near clipping plane.
*/
void setFocusDistance(float distance) noexcept;
//! Returns the focus distance in world units
float getFocusDistance() const noexcept;
/**
* Returns the inverse of a projection matrix.
*
* \param p the projection matrix to inverse
* \returns the inverse of the projection matrix \p p
*
* \warning the projection matrix to invert must have one of the form below:
* - perspective projection
*
* \f$
* \left(
* \begin{array}{cccc}
* a & 0 & tx & 0 \\
* 0 & b & ty & 0 \\
* 0 & 0 & tz & c \\
* 0 & 0 & -1 & 0 \\
* \end{array}
* \right)
* \f$
*
* - orthographic projection
*
* \f$
* \left(
* \begin{array}{cccc}
* a & 0 & 0 & tx \\
* 0 & b & 0 & ty \\
* 0 & 0 & c & tz \\
* 0 & 0 & 0 & 1 \\
* \end{array}
* \right)
* \f$
*/
static math::mat4 inverseProjection(const math::mat4& p) noexcept;
/**
* Returns the inverse of a projection matrix.
* @see inverseProjection(const math::mat4&)
*/
static math::mat4f inverseProjection(const math::mat4f& p) noexcept;
/**
* Helper to compute the effective focal length taking into account the focus distance
*
* @param focalLength focal length in any unit (e.g. [m] or [mm])
* @param focusDistance focus distance in same unit as focalLength
* @return the effective focal length in same unit as focalLength
*/
static double computeEffectiveFocalLength(double focalLength, double focusDistance) noexcept;
/**
* Helper to compute the effective field-of-view taking into account the focus distance
*
* @param fovInDegrees full field of view in degrees
* @param focusDistance focus distance in meters [m]
* @return effective full field of view in degrees
*/
static double computeEffectiveFov(double fovInDegrees, double focusDistance) noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_CAMERA_H

210
ios/include/filament/Color.h Normal file
View File

@@ -0,0 +1,210 @@
/*
* 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_COLOR_H
#define TNT_FILAMENT_COLOR_H
#include <utils/compiler.h>
#include <math/vec3.h>
#include <math/vec4.h>
namespace filament {
//! RGB color in linear space
using LinearColor = math::float3;
//! RGB color in sRGB space
using sRGBColor = math::float3;
//! RGBA color in linear space, with alpha
using LinearColorA = math::float4;
//! RGBA color in sRGB space, with alpha
using sRGBColorA = math::float4;
//! types of RGB colors
enum class RgbType : uint8_t {
sRGB, //!< the color is defined in sRGB space
LINEAR, //!< the color is defined in linear space
};
//! types of RGBA colors
enum class RgbaType : uint8_t {
/**
* the color is defined in sRGB space and the RGB values
* have not been premultiplied by the alpha (for instance, a 50%
* transparent red is <1,0,0,0.5>)
*/
sRGB,
/**
* the color is defined in linear space and the RGB values
* have not been premultiplied by the alpha (for instance, a 50%
* transparent red is <1,0,0,0.5>)
*/
LINEAR,
/**
* the color is defined in sRGB space and the RGB values
* have been premultiplied by the alpha (for instance, a 50%
* transparent red is <0.5,0,0,0.5>)
*/
PREMULTIPLIED_sRGB,
/**
* the color is defined in linear space and the RGB values
* have been premultiplied by the alpha (for instance, a 50%
* transparent red is <0.5,0,0,0.5>)
*/
PREMULTIPLIED_LINEAR
};
//! type of color conversion to use when converting to/from sRGB and linear spaces
enum ColorConversion {
ACCURATE, //!< accurate conversion using the sRGB standard
FAST //!< fast conversion using a simple gamma 2.2 curve
};
/**
* Utilities to manipulate and convert colors
*/
class UTILS_PUBLIC Color {
public:
//! converts an RGB color to linear space, the conversion depends on the specified type
static LinearColor toLinear(RgbType type, math::float3 color);
//! converts an RGBA color to linear space, the conversion depends on the specified type
static LinearColorA toLinear(RgbaType type, math::float4 color);
//! converts an RGB color in sRGB space to an RGB color in linear space
template<ColorConversion = ACCURATE>
static LinearColor toLinear(sRGBColor const& color);
//! converts an RGB color in linear space to an RGB color in sRGB space
template<ColorConversion = ACCURATE>
static sRGBColor toSRGB(LinearColor const& color);
/**
* converts an RGBA color in sRGB space to an RGBA color in linear space
* the alpha component is left unmodified
*/
template<ColorConversion = ACCURATE>
static LinearColorA toLinear(sRGBColorA const& color);
/**
* converts an RGBA color in linear space to an RGBA color in sRGB space
* the alpha component is left unmodified
*/
template<ColorConversion = ACCURATE>
static sRGBColorA toSRGB(LinearColorA const& color);
/**
* converts a correlated color temperature to a linear RGB color in sRGB
* space the temperature must be expressed in kelvin and must be in the
* range 1,000K to 15,000K
*/
static LinearColor cct(float K);
/**
* converts a CIE standard illuminant series D to a linear RGB color in
* sRGB space the temperature must be expressed in kelvin and must be in
* the range 4,000K to 25,000K
*/
static LinearColor illuminantD(float K);
/**
* computes the Beer-Lambert absorption coefficients from the specified
* transmittance color and distance. The computed absorption will guarantee
* the white light will become the specified color at the specified distance.
* The output of this function can be used as the absorption parameter of
* materials that use refraction.
*
* @param color the desired linear RGB color in sRGB space
* @param distance the distance at which white light should become the specified color
*
* @return absorption coefficients for the Beer-Lambert law
*/
static math::float3 absorptionAtDistance(LinearColor const& color, float distance);
private:
static math::float3 sRGBToLinear(math::float3 color) noexcept;
static math::float3 linearToSRGB(math::float3 color) noexcept;
};
// Use the default implementation from the header
template<>
inline LinearColor Color::toLinear<FAST>(sRGBColor const& color) {
return pow(color, 2.2f);
}
template<>
inline LinearColorA Color::toLinear<FAST>(sRGBColorA const& color) {
return LinearColorA{pow(color.rgb, 2.2f), color.a};
}
template<>
inline LinearColor Color::toLinear<ACCURATE>(sRGBColor const& color) {
return sRGBToLinear(color);
}
template<>
inline LinearColorA Color::toLinear<ACCURATE>(sRGBColorA const& color) {
return LinearColorA{sRGBToLinear(color.rgb), color.a};
}
// Use the default implementation from the header
template<>
inline sRGBColor Color::toSRGB<FAST>(LinearColor const& color) {
return pow(color, 1.0f / 2.2f);
}
template<>
inline sRGBColorA Color::toSRGB<FAST>(LinearColorA const& color) {
return sRGBColorA{pow(color.rgb, 1.0f / 2.2f), color.a};
}
template<>
inline sRGBColor Color::toSRGB<ACCURATE>(LinearColor const& color) {
return linearToSRGB(color);
}
template<>
inline sRGBColorA Color::toSRGB<ACCURATE>(LinearColorA const& color) {
return sRGBColorA{linearToSRGB(color.rgb), color.a};
}
inline LinearColor Color::toLinear(RgbType type, math::float3 color) {
return (type == RgbType::LINEAR) ? color : Color::toLinear<ACCURATE>(color);
}
// converts an RGBA color to linear space
// the conversion depends on the specified type
inline LinearColorA Color::toLinear(RgbaType type, math::float4 color) {
switch (type) {
case RgbaType::sRGB:
return Color::toLinear<ACCURATE>(color) * math::float4{color.a, color.a, color.a, 1.0f};
case RgbaType::LINEAR:
return color * math::float4{color.a, color.a, color.a, 1.0f};
case RgbaType::PREMULTIPLIED_sRGB:
return Color::toLinear<ACCURATE>(color);
case RgbaType::PREMULTIPLIED_LINEAR:
return color;
}
}
} // namespace filament
#endif // TNT_FILAMENT_COLOR_H

405
ios/include/filament/ColorGrading.h Normal file
View File

@@ -0,0 +1,405 @@
/*
* Copyright (C) 2020 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_COLOR_GRADING_H
#define TNT_FILAMENT_COLOR_GRADING_H
#include <filament/FilamentAPI.h>
#include <filament/ToneMapper.h>
#include <utils/compiler.h>
#include <math/mathfwd.h>
namespace filament {
class Engine;
class FColorGrading;
/**
* ColorGrading is used to transform (either to modify or correct) the colors of the HDR buffer
* rendered by Filament. Color grading transforms are applied after lighting, and after any lens
* effects (bloom for instance), and include tone mapping.
*
* Creation, usage and destruction
* ===============================
*
* A ColorGrading object is created using the ColorGrading::Builder and destroyed by calling
* Engine::destroy(const ColorGrading*). A ColorGrading object is meant to be set on a View.
*
* ~~~~~~~~~~~{.cpp}
* filament::Engine* engine = filament::Engine::create();
*
* filament::ColorGrading* colorGrading = filament::ColorGrading::Builder()
* .toneMapping(filament::ColorGrading::ToneMapping::ACES)
* .build(*engine);
*
* myView->setColorGrading(colorGrading);
*
* engine->destroy(colorGrading);
* ~~~~~~~~~~~
*
* Performance
* ===========
*
* Creating a new ColorGrading object may be more expensive than other Filament objects as a
* 3D LUT may need to be generated. The generation of a 3D LUT, if necessary, may happen on
* the CPU.
*
* Ordering
* ========
*
* The various transforms held by ColorGrading are applied in the following order:
* - Exposure
* - White balance
* - Channel mixer
* - Shadows/mid-tones/highlights
* - Slope/offset/power (CDL)
* - Contrast
* - Vibrance
* - Saturation
* - Curves
* - Tone mapping
* - Luminance scaling
*
* Defaults
* ========
*
* Here are the default color grading options:
* - Exposure: 0.0
* - White balance: temperature 0, and tint 0
* - Channel mixer: red {1,0,0}, green {0,1,0}, blue {0,0,1}
* - Shadows/mid-tones/highlights: shadows {1,1,1,0}, mid-tones {1,1,1,0}, highlights {1,1,1,0},
* ranges {0,0.333,0.550,1}
* - Slope/offset/power: slope 1.0, offset 0.0, and power 1.0
* - Contrast: 1.0
* - Vibrance: 1.0
* - Saturation: 1.0
* - Curves: gamma {1,1,1}, midPoint {1,1,1}, and scale {1,1,1}
* - Tone mapping: ACESLegacyToneMapper
* - Luminance scaling: false
*
* @see View
*/
class UTILS_PUBLIC ColorGrading : public FilamentAPI {
struct BuilderDetails;
public:
enum class QualityLevel : uint8_t {
LOW,
MEDIUM,
HIGH,
ULTRA
};
/**
* List of available tone-mapping operators.
*
* @deprecated Use Builder::toneMapper(ToneMapper*) instead
*/
enum class UTILS_DEPRECATED ToneMapping : uint8_t {
LINEAR = 0, //!< Linear tone mapping (i.e. no tone mapping)
ACES_LEGACY = 1, //!< ACES tone mapping, with a brightness modifier to match Filament's legacy tone mapper
ACES = 2, //!< ACES tone mapping
FILMIC = 3, //!< Filmic tone mapping, modelled after ACES but applied in sRGB space
DISPLAY_RANGE = 4, //!< Tone mapping used to validate/debug scene exposure
};
//! Use Builder to construct a ColorGrading object instance
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Sets the quality level of the color grading. When color grading is implemented using
* a 3D LUT, the quality level may impact the resolution and bit depth of the backing
* 3D texture. For instance, a low quality level will use a 16x16x16 10 bit LUT, a medium
* quality level will use a 32x32x32 10 bit LUT, a high quality will use a 32x32x32 16 bit
* LUT, and a ultra quality will use a 64x64x64 16 bit LUT.
*
* The default quality is medium.
*
* @param qualityLevel The desired quality of the color grading process
*
* @return This Builder, for chaining calls
*/
Builder& quality(QualityLevel qualityLevel) noexcept;
/**
* Selects the tone mapping operator to apply to the HDR color buffer as the last
* operation of the color grading post-processing step.
*
* The default tone mapping operator is ACESLegacyToneMapper.
*
* The specified tone mapper must have a lifecycle that exceeds the lifetime of
* this builder. Since the build(Engine&) method is synchronous, it is safe to
* delete the tone mapper object after that finishes executing.
*
* @param toneMapper The tone mapping operator to apply to the HDR color buffer
*
* @return This Builder, for chaining calls
*/
Builder& toneMapper(const ToneMapper* toneMapper) noexcept;
/**
* Selects the tone mapping operator to apply to the HDR color buffer as the last
* operation of the color grading post-processing step.
*
* The default tone mapping operator is ACES_LEGACY.
*
* @param toneMapping The tone mapping operator to apply to the HDR color buffer
*
* @return This Builder, for chaining calls
*
* @deprecated Use toneMapper(ToneMapper*) instead
*/
UTILS_DEPRECATED
Builder& toneMapping(ToneMapping toneMapping) noexcept;
/**
* Enables or disables the luminance scaling component (LICH) from the exposure value
* invariant luminance system (EVILS). When this setting is enabled, pixels with high
* chromatic values will roll-off to white to offer a more natural rendering. This step
* also helps avoid undesirable hue skews caused by out of gamut colors clipped
* to the destination color gamut.
*
* When luminance scaling is enabled, tone mapping is performed on the luminance of each
* pixel instead of per-channel.
*
* @param luminanceScaling Enables or disables EVILS post-tone mapping
*
* @return This Builder, for chaining calls
*/
Builder& luminanceScaling(bool luminanceScaling) noexcept;
/**
* Adjusts the exposure of this image. The exposure is specified in stops:
* each stop brightens (positive values) or darkens (negative values) the image by
* a factor of 2. This means that an exposure of 3 will brighten the image 8 times
* more than an exposure of 0 (2^3 = 8 and 2^0 = 1). Contrary to the camera's exposure,
* this setting is applied after all post-processing (bloom, etc.) are applied.
*
* @param exposure Value in EV stops. Can be negative, 0, or positive.
*
* @return This Builder, for chaining calls
*/
Builder& exposure(float exposure) noexcept;
/**
* Adjusts the while balance of the image. This can be used to remove color casts
* and correct the appearance of the white point in the scene, or to alter the
* overall chromaticity of the image for artistic reasons (to make the image appear
* cooler or warmer for instance).
*
* The while balance adjustment is defined with two values:
* - Temperature, to modify the color temperature. This value will modify the colors
* on a blue/yellow axis. Lower values apply a cool color temperature, and higher
* values apply a warm color temperature. The lowest value, -1.0f, is equivalent to
* a temperature of 50,000K. The highest value, 1.0f, is equivalent to a temperature
* of 2,000K.
* - Tint, to modify the colors on a green/magenta axis. The lowest value, -1.0f, will
* apply a strong green cast, and the highest value, 1.0f, will apply a strong magenta
* cast.
*
* Both values are expected to be in the range [-1.0..+1.0]. Values outside of that
* range will be clipped to that range.
*
* @param temperature Modification on the blue/yellow axis, as a value between -1.0 and +1.0.
* @param tint Modification on the green/magenta axis, as a value between -1.0 and +1.0.
*
* @return This Builder, for chaining calls
*/
Builder& whiteBalance(float temperature, float tint) noexcept;
/**
* The channel mixer adjustment modifies each output color channel using the specified
* mix of the source color channels.
*
* By default each output color channel is set to use 100% of the corresponding source
* channel and 0% of the other channels. For instance, the output red channel is set to
* {1.0, 0.0, 1.0} or 100% red, 0% green and 0% blue.
*
* Each output channel can add or subtract data from the source channel by using values
* in the range [-2.0..+2.0]. Values outside of that range will be clipped to that range.
*
* Using the channel mixer adjustment you can for instance create a monochrome output
* by setting all 3 output channels to the same mix. For instance: {0.4, 0.4, 0.2} for
* all 3 output channels(40% red, 40% green and 20% blue).
*
* More complex mixes can be used to create more complex effects. For instance, here is
* a mix that creates a sepia tone effect:
* - outRed = {0.255, 0.858, 0.087}
* - outGreen = {0.213, 0.715, 0.072}
* - outBlue = {0.170, 0.572, 0.058}
*
* @param outRed The mix of source RGB for the output red channel, between -2.0 and +2.0
* @param outGreen The mix of source RGB for the output green channel, between -2.0 and +2.0
* @param outBlue The mix of source RGB for the output blue channel, between -2.0 and +2.0
*
* @return This Builder, for chaining calls
*/
Builder& channelMixer(
math::float3 outRed, math::float3 outGreen, math::float3 outBlue) noexcept;
/**
* Adjusts the colors separately in 3 distinct tonal ranges or zones: shadows, mid-tones,
* and highlights.
*
* The tonal zones are by the ranges parameter: the x and y components define the beginning
* and end of the transition from shadows to mid-tones, and the z and w components define
* the beginning and end of the transition from mid-tones to highlights.
*
* A smooth transition is applied between the zones which means for instance that the
* correction color of the shadows range will partially apply to the mid-tones, and the
* other way around. This ensure smooth visual transitions in the final image.
*
* Each correction color is defined as a linear RGB color and a weight. The weight is a
* value (which may be positive or negative) that is added to the linear RGB color before
* mixing. This can be used to darken or brighten the selected tonal range.
*
* Shadows/mid-tones/highlights adjustment are performed linear space.
*
* @param shadows Linear RGB color (.rgb) and weight (.w) to apply to the shadows
* @param midtones Linear RGB color (.rgb) and weight (.w) to apply to the mid-tones
* @param highlights Linear RGB color (.rgb) and weight (.w) to apply to the highlights
* @param ranges Range of the shadows (x and y), and range of the highlights (z and w)
*
* @return This Builder, for chaining calls
*/
Builder& shadowsMidtonesHighlights(
math::float4 shadows, math::float4 midtones, math::float4 highlights,
math::float4 ranges) noexcept;
/**
* Applies a slope, offset, and power, as defined by the ASC CDL (American Society of
* Cinematographers Color Decision List) to the image. The CDL can be used to adjust the
* colors of different tonal ranges in the image.
*
* The ASC CDL is similar to the lift/gamma/gain controls found in many color grading tools.
* Lift is equivalent to a combination of offset and slope, gain is equivalent to slope,
* and gamma is equivalent to power.
*
* The slope and power values must be strictly positive. Values less than or equal to 0 will
* be clamped to a small positive value, offset can be any positive or negative value.
*
* Version 1.2 of the ASC CDL adds saturation control, which is here provided as a separate
* API. See the saturation() method for more information.
*
* Slope/offset/power adjustments are performed in log space.
*
* @param slope Multiplier of the input color, must be a strictly positive number
* @param offset Added to the input color, can be a negative or positive number, including 0
* @param power Power exponent of the input color, must be a strictly positive number
*
* @return This Builder, for chaining calls
*/
Builder& slopeOffsetPower(math::float3 slope, math::float3 offset, math::float3 power) noexcept;
/**
* Adjusts the contrast of the image. Lower values decrease the contrast of the image
* (the tonal range is narrowed), and higher values increase the contrast of the image
* (the tonal range is widened). A value of 1.0 has no effect.
*
* The contrast is defined as a value in the range [0.0...2.0]. Values outside of that
* range will be clipped to that range.
*
* Contrast adjustment is performed in log space.
*
* @param contrast Contrast expansion, between 0.0 and 2.0. 1.0 leaves contrast unaffected
*
* @return This Builder, for chaining calls
*/
Builder& contrast(float contrast) noexcept;
/**
* Adjusts the saturation of the image based on the input color's saturation level.
* Colors with a high level of saturation are less affected than colors with low saturation
* levels.
*
* Lower vibrance values decrease intensity of the colors present in the image, and
* higher values increase the intensity of the colors in the image. A value of 1.0 has
* no effect.
*
* The vibrance is defined as a value in the range [0.0...2.0]. Values outside of that
* range will be clipped to that range.
*
* Vibrance adjustment is performed in linear space.
*
* @param vibrance Vibrance, between 0.0 and 2.0. 1.0 leaves vibrance unaffected
*
* @return This Builder, for chaining calls
*/
Builder& vibrance(float vibrance) noexcept;
/**
* Adjusts the saturation of the image. Lower values decrease intensity of the colors
* present in the image, and higher values increase the intensity of the colors in the
* image. A value of 1.0 has no effect.
*
* The saturation is defined as a value in the range [0.0...2.0]. Values outside of that
* range will be clipped to that range.
*
* Saturation adjustment is performed in linear space.
*
* @param saturation Saturation, between 0.0 and 2.0. 1.0 leaves saturation unaffected
*
* @return This Builder, for chaining calls
*/
Builder& saturation(float saturation) noexcept;
/**
* Applies a curve to each RGB channel of the image. Each curve is defined by 3 values:
* a gamma value applied to the shadows only, a mid-point indicating where shadows stop
* and highlights start, and a scale factor for the highlights.
*
* The gamma and mid-point must be strictly positive values. If they are not, they will be
* clamped to a small positive value. The scale can be any negative of positive value.
*
* Curves are applied in linear space.
*
* @param shadowGamma Power value to apply to the shadows, must be strictly positive
* @param midPoint Mid-point defining where shadows stop and highlights start, must be strictly positive
* @param highlightScale Scale factor for the highlights, can be any negative or positive value
*
* @return This Builder, for chaining calls
*/
Builder& curves(math::float3 shadowGamma, math::float3 midPoint, math::float3 highlightScale) noexcept;
/**
* Creates the ColorGrading object and returns a pointer to it.
*
* @param engine Reference to the filament::Engine to associate this ColorGrading with.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*/
ColorGrading* build(Engine& engine);
private:
friend class FColorGrading;
};
};
} // namespace filament
#endif // TNT_FILAMENT_COLOR_GRADING_H

131
ios/include/filament/DebugRegistry.h Normal file
View File

@@ -0,0 +1,131 @@
/*
* Copyright (C) 2018 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_DEBUG_H
#define TNT_FILAMENT_DEBUG_H
#include <filament/FilamentAPI.h>
#include <utils/compiler.h>
#include <math/mathfwd.h>
#include <stdint.h>
namespace filament {
/**
* A registry of runtime properties used exclusively for debugging
*
* Filament exposes a few properties that can be queried and set, which control certain debugging
* features of the engine. These properties can be set at runtime at anytime.
*
*/
class UTILS_PUBLIC DebugRegistry : public FilamentAPI {
public:
/**
* Type of a property
*/
enum Type {
BOOL, INT, FLOAT, FLOAT2, FLOAT3, FLOAT4
};
/**
* Information about a property
*/
struct Property {
const char* name; //!< property name
Type type; //!< property type
};
struct PropertyArray {
Property const* array;
size_t size;
};
/**
* Queries the list of all available properties.
*
* @return A pair containing a pointer to a Property array and the size of this array.
*/
PropertyArray getProperties() const noexcept;
/**
* Queries whether a property exists
* @param name The name of the property to query
* @return true if the property exists, false otherwise
*/
bool hasProperty(const char* name) const noexcept;
/**
* Queries the address of a property's data from its name
* @param name Name of the property we want the data address of
* @return Address of the data of the \p name property
* @{
*/
void* getPropertyAddress(const char* name) noexcept;
template<typename T>
inline T* getPropertyAddress(const char* name) noexcept {
return static_cast<T*>(getPropertyAddress(name));
}
template<typename T>
inline bool getPropertyAddress(const char* name, T** p) noexcept {
*p = getPropertyAddress<T>(name);
return *p != nullptr;
}
/** @}*/
/**
* Set the value of a property
* @param name Name of the property to set the value of
* @param v Value to set
* @return true if the operation was successful, false otherwise.
* @{
*/
bool setProperty(const char* name, bool v) noexcept;
bool setProperty(const char* name, int v) noexcept;
bool setProperty(const char* name, float v) noexcept;
bool setProperty(const char* name, math::float2 v) noexcept;
bool setProperty(const char* name, math::float3 v) noexcept;
bool setProperty(const char* name, math::float4 v) noexcept;
/** @}*/
/**
* Get the value of a property
* @param name Name of the property to get the value of
* @param v A pointer to a variable which will hold the result
* @return true if the call was successful and \p v was updated
* @{
*/
bool getProperty(const char* name, bool* v) const noexcept;
bool getProperty(const char* name, int* v) const noexcept;
bool getProperty(const char* name, float* v) const noexcept;
bool getProperty(const char* name, math::float2* v) const noexcept;
bool getProperty(const char* name, math::float3* v) const noexcept;
bool getProperty(const char* name, math::float4* v) const noexcept;
/** @}*/
};
} // namespace filament
#endif /* TNT_FILAMENT_DEBUG_H */

543
ios/include/filament/Engine.h Normal file
View File

@@ -0,0 +1,543 @@
/*
* 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.
*/
#ifndef TNT_FILAMENT_ENGINE_H
#define TNT_FILAMENT_ENGINE_H
#include <backend/Platform.h>
#include <utils/compiler.h>
namespace utils {
class Entity;
class EntityManager;
class JobSystem;
} // namespace utils
namespace filament {
class BufferObject;
class Camera;
class ColorGrading;
class DebugRegistry;
class Fence;
class IndexBuffer;
class IndirectLight;
class Material;
class MaterialInstance;
class Renderer;
class RenderTarget;
class Scene;
class Skybox;
class Stream;
class SwapChain;
class Texture;
class VertexBuffer;
class View;
class LightManager;
class RenderableManager;
class TransformManager;
/**
* Engine is filament's main entry-point.
*
* An Engine instance main function is to keep track of all resources created by the user and
* manage the rendering thread as well as the hardware renderer.
*
* To use filament, an Engine instance must be created first:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* #include <filament/Engine.h>
* using namespace filament;
*
* Engine* engine = Engine::create();
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Engine essentially represents (or is associated to) a hardware context
* (e.g. an OpenGL ES context).
*
* Rendering typically happens in an operating system's window (which can be full screen), such
* window is managed by a filament.Renderer.
*
* A typical filament render loop looks like this:
*
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* #include <filament/Engine.h>
* #include <filament/Renderer.h>
* #include <filament/Scene.h>
* #include <filament/View.h>
* using namespace filament;
*
* Engine* engine = Engine::create();
* SwapChain* swapChain = engine->createSwapChain(nativeWindow);
* Renderer* renderer = engine->createRenderer();
* Scene* scene = engine->createScene();
* View* view = engine->createView();
*
* view->setScene(scene);
*
* do {
* // typically we wait for VSYNC and user input events
* if (renderer->beginFrame(swapChain)) {
* renderer->render(view);
* renderer->endFrame();
* }
* } while (!quit);
*
* engine->destroy(view);
* engine->destroy(scene);
* engine->destroy(renderer);
* engine->destroy(swapChain);
* Engine::destroy(&engine); // clears engine*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Resource Tracking
* =================
*
* Each Engine instance keeps track of all objects created by the user, such as vertex and index
* buffers, lights, cameras, etc...
* The user is expected to free those resources, however, leaked resources are freed when the
* engine instance is destroyed and a warning is emitted in the console.
*
* Thread safety
* =============
*
* An Engine instance is not thread-safe. The implementation makes no attempt to synchronize
* calls to an Engine instance methods.
* If multi-threading is needed, synchronization must be external.
*
* Multi-threading
* ===============
*
* When created, the Engine instance starts a render thread as well as multiple worker threads,
* these threads have an elevated priority appropriate for rendering, based on the platform's
* best practices. The number of worker threads depends on the platform and is automatically
* chosen for best performance.
*
* On platforms with asymmetric cores (e.g. ARM's Big.Little), Engine makes some educated guesses
* as to which cores to use for the render thread and worker threads. For example, it'll try to
* keep an OpenGL ES thread on a Big core.
*
* Swap Chains
* ===========
*
* A swap chain represents an Operating System's *native* renderable surface. Typically it's a window
* or a view. Because a SwapChain is initialized from a native object, it is given to filament
* as a `void*`, which must be of the proper type for each platform filament is running on.
*
* @see SwapChain
*
*
* @see Renderer
*/
class UTILS_PUBLIC Engine {
public:
using Platform = backend::Platform;
using Backend = backend::Backend;
/**
* Creates an instance of Engine
*
* @param backend Which driver backend to use.
*
* @param platform A pointer to an object that implements Platform. If this is
* provided, then this object is used to create the hardware context
* and expose platform features to it.
*
* If not provided (or nullptr is used), an appropriate Platform
* is created automatically.
*
* All methods of this interface are called from filament's
* render thread, which is different from the main thread.
*
* The lifetime of \p platform must exceed the lifetime of
* the Engine object.
*
* @param sharedGLContext A platform-dependant OpenGL context used as a shared context
* when creating filament's internal context.
* Setting this parameter will force filament to use the OpenGL
* implementation (instead of Vulkan for instance).
*
*
* @return A pointer to the newly created Engine, or nullptr if the Engine couldn't be created.
*
* nullptr if the GPU driver couldn't be initialized, for instance if it doesn't
* support the right version of OpenGL or OpenGL ES.
*
* @exception utils::PostConditionPanic can be thrown if there isn't enough memory to
* allocate the command buffer. If exceptions are disabled, this condition if fatal and
* this function will abort.
*
* \remark
* This method is thread-safe.
*/
static Engine* create(Backend backend = Backend::DEFAULT,
Platform* platform = nullptr, void* sharedGLContext = nullptr);
#if UTILS_HAS_THREADING
/**
* A callback used with Engine::createAsync() called once the engine is initialized and it is
* safe to call Engine::getEngine(token). This callback is invoked from an arbitrary worker
* thread. Engine::getEngine() CANNOT be called from that thread, instead it must be called
* from the same thread than Engine::createAsync() was called from.
*
* @param user User provided parameter given in createAsync().
*
* @param token An opaque token used to call Engine::getEngine().
*/
using CreateCallback = void(void* user, void* token);
/**
* Creates an instance of Engine asynchronously
*
* @param callback Callback called once the engine is initialized and it is safe to
* call Engine::getEngine.
*
* @param user A user provided pointer that is given back to callback unmodified.
*
* @param backend Which driver backend to use.
*
* @param platform A pointer to an object that implements Platform. If this is
* provided, then this object is used to create the hardware context
* and expose platform features to it.
*
* If not provided (or nullptr is used), an appropriate Platform
* is created automatically.
*
* All methods of this interface are called from filament's
* render thread, which is different from the main thread.
*
* The lifetime of \p platform must exceed the lifetime of
* the Engine object.
*
* @param sharedGLContext A platform-dependant OpenGL context used as a shared context
* when creating filament's internal context.
* Setting this parameter will force filament to use the OpenGL
* implementation (instead of Vulkan for instance).
*/
static void createAsync(CreateCallback callback, void* user,
Backend backend = Backend::DEFAULT,
Platform* platform = nullptr, void* sharedGLContext = nullptr);
/**
* Retrieve an Engine* from createAsync(). This must be called from the same thread than
* Engine::createAsync() was called from.
*
* @param token An opaque token given in the createAsync() callback function.
*
* @return A pointer to the newly created Engine, or nullptr if the Engine couldn't be created.
*
* @exception utils::PostConditionPanic can be thrown if there isn't enough memory to
* allocate the command buffer. If exceptions are disabled, this condition if fatal and
* this function will abort.
*/
static Engine* getEngine(void* token);
#endif
/**
* Destroy the Engine instance and all associated resources.
*
* Engine.destroy() should be called last and after all other resources have been destroyed,
* it ensures all filament resources are freed.
*
* Destroy performs the following tasks:
* 1. Destroy all internal software and hardware resources.
* 2. Free all user allocated resources that are not already destroyed and logs a warning.
* This indicates a "leak" in the user's code.
* 3. Terminate the rendering engine's thread.
*
* @param engine A pointer to the filament.Engine* to be destroyed.
* \p engine is cleared upon return.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* #include <filament/Engine.h>
* using namespace filament;
*
* Engine* engine = Engine::create();
* Engine::destroy(&engine); // clears engine*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* \remark
* This method is thread-safe.
*/
static void destroy(Engine** engine);
/**
* Destroy the Engine instance and all associated resources.
*
* Engine.destroy() should be called last and after all other resources have been destroyed,
* it ensures all filament resources are freed.
*
* Destroy performs the following tasks:
* 1. Destroy all internal software and hardware resources.
* 2. Free all user allocated resources that are not already destroyed and logs a warning.
* This indicates a "leak" in the user's code.
* 3. Terminate the rendering engine's thread.
*
* @param engine A pointer to the filament.Engine to be destroyed.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* #include <filament/Engine.h>
* using namespace filament;
*
* Engine* engine = Engine::create();
* Engine::destroy(engine);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* \remark
* This method is thread-safe.
*/
static void destroy(Engine* engine);
/**
* @return EntityManager used by filament
*/
utils::EntityManager& getEntityManager() noexcept;
/**
* @return RenderableManager reference
*/
RenderableManager& getRenderableManager() noexcept;
/**
* @return LightManager reference
*/
LightManager& getLightManager() noexcept;
/**
* @return TransformManager reference
*/
TransformManager& getTransformManager() noexcept;
/**
* Helper to enable accurate translations.
* If you need this Engine to handle a very large world space, one way to achieve this
* automatically is to enable accurate translations in the TransformManager. This helper
* provides a convenient way of doing that.
* This is typically called once just after creating the Engine.
*/
void enableAccurateTranslations() noexcept;
/**
* Creates a SwapChain from the given Operating System's native window handle.
*
* @param nativeWindow An opaque native window handle. e.g.: on Android this is an
* `ANativeWindow*`.
* @param flags One or more configuration flags as defined in `SwapChain`.
*
* @return A pointer to the newly created SwapChain or nullptr if it couldn't be created.
*
* @see Renderer.beginFrame()
*/
SwapChain* createSwapChain(void* nativeWindow, uint64_t flags = 0) noexcept;
/**
* Creates a headless SwapChain.
*
* @param width Width of the drawing buffer in pixels.
* @param height Height of the drawing buffer in pixels.
* @param flags One or more configuration flags as defined in `SwapChain`.
*
* @return A pointer to the newly created SwapChain or nullptr if it couldn't be created.
*
* @see Renderer.beginFrame()
*/
SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags = 0) noexcept;
/**
* Creates a renderer associated to this engine.
*
* A Renderer is intended to map to a *window* on screen.
*
* @return A pointer to the newly created Renderer or nullptr if it couldn't be created.
*/
Renderer* createRenderer() noexcept;
/**
* Creates a View.
*
* @return A pointer to the newly created View or nullptr if it couldn't be created.
*/
View* createView() noexcept;
/**
* Creates a Scene.
*
* @return A pointer to the newly created Scene or nullptr if it couldn't be created.
*/
Scene* createScene() noexcept;
/**
* Creates a Camera component.
*
* @param entity Entity to add the camera component to.
* @return A pointer to the newly created Camera or nullptr if it couldn't be created.
*/
Camera* createCamera(utils::Entity entity) noexcept;
/**
* Returns the Camera component of the given entity.
*
* @param entity An entity.
* @return A pointer to the Camera component for this entity or nullptr if the entity didn't
* have a Camera component. The pointer is valid until destroyCameraComponent()
* is called or the entity itself is destroyed.
*/
Camera* getCameraComponent(utils::Entity entity) noexcept;
/**
* Destroys the Camera component associated with the given entity.
*
* @param entity An entity.
*/
void destroyCameraComponent(utils::Entity entity) noexcept;
/**
* Creates a Fence.
*
* @return A pointer to the newly created Fence or nullptr if it couldn't be created.
*/
Fence* createFence() noexcept;
bool destroy(const BufferObject* p); //!< Destroys a BufferObject object.
bool destroy(const VertexBuffer* p); //!< Destroys an VertexBuffer object.
bool destroy(const Fence* p); //!< Destroys a Fence object.
bool destroy(const IndexBuffer* p); //!< Destroys an IndexBuffer object.
bool destroy(const IndirectLight* p); //!< Destroys an IndirectLight object.
/**
* Destroys a Material object
* @param p the material object to destroy
* @attention All MaterialInstance of the specified material must be destroyed before
* destroying it.
* @exception utils::PreConditionPanic is thrown if some MaterialInstances remain.
* no-op if exceptions are disabled and some MaterialInstances remain.
*/
bool destroy(const Material* p);
bool destroy(const MaterialInstance* p); //!< Destroys a MaterialInstance object.
bool destroy(const Renderer* p); //!< Destroys a Renderer object.
bool destroy(const Scene* p); //!< Destroys a Scene object.
bool destroy(const Skybox* p); //!< Destroys a SkyBox object.
bool destroy(const ColorGrading* p); //!< Destroys a ColorGrading object.
bool destroy(const SwapChain* p); //!< Destroys a SwapChain object.
bool destroy(const Stream* p); //!< Destroys a Stream object.
bool destroy(const Texture* p); //!< Destroys a Texture object.
bool destroy(const RenderTarget* p); //!< Destroys a RenderTarget object.
bool destroy(const View* p); //!< Destroys a View object.
void destroy(utils::Entity e); //!< Destroys all filament-known components from this entity
/**
* Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks until
* all commands to this point are executed. Note that this doesn't guarantee that the
* hardware is actually finished.
*
* <p>This is typically used right after destroying the <code>SwapChain</code>,
* in cases where a guarantee about the <code>SwapChain</code> destruction is needed in a
* timely fashion, such as when responding to Android's
* <code>android.view.SurfaceHolder.Callback.surfaceDestroyed</code></p>
*/
void flushAndWait();
void flush();
/**
* Returns the default Material.
*
* The default material is 80% white and uses the Material.Shading.LIT shading.
*
* @return A pointer to the default Material instance (a singleton).
*/
const Material* getDefaultMaterial() const noexcept;
/**
* Returns the resolved backend.
*/
Backend getBackend() const noexcept;
/**
* Returns the Platform object that belongs to this Engine.
*
* When Engine::create is called with no platform argument, Filament creates an appropriate
* Platform subclass automatically. The specific subclass created depends on the backend and
* OS. For example, when the OpenGL backend is used, the Platform object will be a descendant of
* OpenGLPlatform.
*
* dynamic_cast should be used to cast the returned Platform object into a specific subclass.
* Note that RTTI must be available to use dynamic_cast.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Platform* platform = engine->getPlatform();
* // static_cast also works, but more dangerous.
* SpecificPlatform* specificPlatform = dynamic_cast<SpecificPlatform*>(platform);
* specificPlatform->platformSpecificMethod();
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* When a custom Platform is passed to Engine::create, Filament will use it instead, and this
* method will return it.
*
* @return A pointer to the Platform object that was provided to Engine::create, or the
* Filament-created one.
*/
Platform* getPlatform() const noexcept;
/**
* Allocate a small amount of memory directly in the command stream. The allocated memory is
* guaranteed to be preserved until the current command buffer is executed
*
* @param size size to allocate in bytes. This should be small (e.g. < 1 KB)
* @param alignment alignment requested
* @return a pointer to the allocated buffer or nullptr if no memory was available.
*
* @note there is no need to destroy this buffer, it will be freed automatically when
* the current command buffer is executed.
*/
void* streamAlloc(size_t size, size_t alignment = alignof(double)) noexcept;
/**
* Invokes one iteration of the render loop, used only on single-threaded platforms.
*
* This should be called every time the windowing system needs to paint (e.g. at 60 Hz).
*/
void execute();
/**
* Retrieves the job system that the Engine has ownership over.
*
* @return JobSystem used by filament
*/
utils::JobSystem& getJobSystem() noexcept;
DebugRegistry& getDebugRegistry() noexcept;
protected:
//! \privatesection
Engine() noexcept = default;
~Engine() = default;
public:
//! \privatesection
Engine(Engine const&) = delete;
Engine(Engine&&) = delete;
Engine& operator=(Engine const&) = delete;
Engine& operator=(Engine&&) = delete;
};
} // namespace filament
#endif // TNT_FILAMENT_ENGINE_H

129
ios/include/filament/Exposure.h Normal file
View File

@@ -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

86
ios/include/filament/Fence.h Normal file
View File

@@ -0,0 +1,86 @@
/*
* Copyright (C) 2016 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_FENCE_H
#define TNT_FILAMENT_FENCE_H
#include <filament/FilamentAPI.h>
#include <backend/DriverEnums.h>
#include <utils/compiler.h>
namespace filament {
/**
* Fence is used to synchronize rendering operations together, with the CPU or with compute.
*
* \note
* Currently Fence only provide client-side synchronization.
*
*/
class UTILS_PUBLIC Fence : public FilamentAPI {
public:
//! Special \p timeout value to disable wait()'s timeout.
static constexpr uint64_t FENCE_WAIT_FOR_EVER = backend::FENCE_WAIT_FOR_EVER;
//! Error codes for Fence::wait()
using FenceStatus = backend::FenceStatus;
/** Mode controls the behavior of the command stream when calling wait()
*
* @attention
* It would be unwise to call `wait(..., Mode::DONT_FLUSH)` from the same thread
* the Fence was created, as it would most certainly create a dead-lock.
*/
enum class Mode : uint8_t {
FLUSH, //!< The command stream is flushed
DONT_FLUSH //!< The command stream is not flushed
};
/**
* Client-side wait on the Fence.
*
* Blocks the current thread until the Fence signals.
*
* @param mode Whether the command stream is flushed before waiting or not.
* @param timeout Wait time out. Using a \p timeout of 0 is a way to query the state of the fence.
* A \p timeout value of FENCE_WAIT_FOR_EVER is used to disable the timeout.
* @return FenceStatus::CONDITION_SATISFIED on success,
* FenceStatus::TIMEOUT_EXPIRED if the time out expired or
* FenceStatus::ERROR in other cases.
* @see #Mode
*/
FenceStatus wait(Mode mode = Mode::FLUSH, uint64_t timeout = FENCE_WAIT_FOR_EVER);
/**
* Client-side wait on a Fence and destroy the Fence.
*
* @param fence Fence object to wait on.
*
* @param mode Whether the command stream is flushed before waiting or not.
*
* @return FenceStatus::CONDITION_SATISFIED on success,
* FenceStatus::ERROR otherwise.
*/
static FenceStatus waitAndDestroy(Fence* fence, Mode mode = Mode::FLUSH);
};
} // namespace filament
#endif // TNT_FILAMENT_FENCE_H

91
ios/include/filament/FilamentAPI.h Normal file
View File

@@ -0,0 +1,91 @@
/*
* 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.
*/
#ifndef TNT_FILAMENT_FILAMENT_API_H
#define TNT_FILAMENT_FILAMENT_API_H
#include <utils/compiler.h>
#include <stddef.h>
namespace filament {
/**
* \privatesection
* FilamentAPI is used to define an API in filament.
* It ensures the class defining the API can't be created, destroyed
* or copied by the caller.
*/
class UTILS_PUBLIC FilamentAPI {
protected:
// disallow creation on the stack
FilamentAPI() noexcept = default;
~FilamentAPI() = default;
public:
// disallow copy and assignment
FilamentAPI(FilamentAPI const&) = delete;
FilamentAPI(FilamentAPI&&) = delete;
FilamentAPI& operator=(FilamentAPI const&) = delete;
FilamentAPI& operator=(FilamentAPI&&) = delete;
// allow placement-new allocation, don't use "noexcept", to avoid compiler null check
static void *operator new (size_t, void* p) { return p; }
// prevent heap allocation
static void *operator new (size_t) = delete;
static void *operator new[] (size_t) = delete;
static void operator delete (void*) = delete;
static void operator delete[](void*) = delete;
};
/**
* \privatesection
* BuilderBase is used to hide the implementation details of builders and ensure a higher
* level of backward binary compatibility.
* The actual implementation is in src/FilamentAPI-impl.h"
*/
template <typename T>
class BuilderBase {
public:
// none of these methods must be implemented inline because it's important that their
// implementation be hidden from the public headers.
template<typename ... ARGS>
explicit BuilderBase(ARGS&& ...) noexcept;
BuilderBase() noexcept;
~BuilderBase() noexcept;
BuilderBase(BuilderBase const& rhs) noexcept;
BuilderBase& operator = (BuilderBase const& rhs) noexcept;
// move ctor and copy operator can be implemented inline and don't need to be exported
BuilderBase(BuilderBase&& rhs) noexcept : mImpl(rhs.mImpl) { rhs.mImpl = nullptr; }
BuilderBase& operator = (BuilderBase&& rhs) noexcept {
auto temp = mImpl;
mImpl = rhs.mImpl;
rhs.mImpl = temp;
return *this;
}
protected:
T* mImpl = nullptr;
inline T* operator->() noexcept { return mImpl; }
inline T const* operator->() const noexcept { return mImpl; }
};
} // namespace filament
#endif // TNT_FILAMENT_FILAMENT_API_H

144
ios/include/filament/Frustum.h Normal file
View File

@@ -0,0 +1,144 @@
/*
* 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_FRUSTUM_H
#define TNT_FILAMENT_FRUSTUM_H
#include <utils/compiler.h>
#include <math/mat4.h>
#include <math/vec3.h>
#include <utils/unwindows.h> // Because we define NEAR and FAR in the Plane enum.
namespace filament {
class Box;
class Culler;
/**
* A frustum defined by six planes
*/
class UTILS_PUBLIC Frustum {
public:
enum class Plane : uint8_t {
LEFT,
RIGHT,
BOTTOM,
TOP,
FAR,
NEAR
};
Frustum() = default;
Frustum(const Frustum& rhs) = default;
Frustum(Frustum&& rhs) noexcept = default;
Frustum& operator=(const Frustum& rhs) = default;
Frustum& operator=(Frustum&& rhs) noexcept = default;
/**
* Creates a frustum from a projection matrix (usually the projection * view matrix)
* @param pv a 4x4 projection matrix
*/
explicit Frustum(const math::mat4f& pv);
/**
* Creates a frustum from 8 corner coordinates.
* @param corners the corners of the frustum
*
* The corners should be specified in this order:
* 0. far bottom left
* 1. far bottom right
* 2. far top left
* 3. far top right
* 4. near bottom left
* 5. near bottom right
* 6. near top left
* 7. near top right
*
* 2----3
* /| /|
* 6----7 |
* | 0--|-1 far
* |/ |/ /
* 4----5 near
*
*/
explicit Frustum(const math::float3 corners[8]);
/**
* Sets the frustum from the given projection matrix
* @param pv a 4x4 projection matrix
*/
void setProjection(const math::mat4f& pv);
/**
* Returns the plane equation parameters with normalized normals
* @param plane Identifier of the plane to retrieve the equation of
* @return A plane equation encoded a float4 R such as R.x*x + R.y*y + R.z*z + R.w = 0
*/
math::float4 getNormalizedPlane(Plane plane) const noexcept;
/**
* Returns a copy of all six frustum planes in left, right, bottom, top, far, near order
* @param planes six plane equations encoded as in getNormalizedPlane() in
* left, right, bottom, top, far, near order
*/
void getNormalizedPlanes(math::float4 planes[6]) const noexcept;
/**
* Returns all six frustum planes in left, right, bottom, top, far, near order
* @return six plane equations encoded as in getNormalizedPlane() in
* left, right, bottom, top, far, near order
*/
math::float4 const* getNormalizedPlanes() const noexcept { return mPlanes; }
/**
* Returns whether a box intersects the frustum (i.e. is visible)
* @param box The box to test against the frustum
* @return true if the box may intersects the frustum, false otherwise. In some situations
* a box that doesn't intersect the frustum might be reported as though it does. However,
* a box that does intersect the frustum is always reported correctly (true).
*/
bool intersects(const Box& box) const noexcept;
/**
* Returns whether a sphere intersects the frustum (i.e. is visible)
* @param sphere A sphere encoded as a center + radius.
* @return true if the sphere may intersects the frustum, false otherwise. In some situations
* a sphere that doesn't intersect the frustum might be reported as though it does. However,
* a sphere that does intersect the frustum is always reported correctly (true).
*/
bool intersects(const math::float4& sphere) const noexcept;
/**
* Returns whether the frustum contains a given point.
* @param p the point to test
* @return the maximum signed distance to the frustum. Negative if p is inside.
*/
float contains(math::float3 p) const noexcept;
private:
friend class Culler;
math::float4 mPlanes[6];
};
} // namespace filament
#endif // TNT_FILAMENT_FRUSTUM_H

125
ios/include/filament/IndexBuffer.h Normal file
View File

@@ -0,0 +1,125 @@
/*
* 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_INDEXBUFFER_H
#define TNT_FILAMENT_INDEXBUFFER_H
#include <filament/FilamentAPI.h>
#include <backend/DriverEnums.h>
#include <backend/BufferDescriptor.h>
#include <utils/compiler.h>
#include <stddef.h>
namespace filament {
class FIndexBuffer;
class Engine;
/**
* A buffer containing vertex indices into a VertexBuffer. Indices can be 16 or 32 bit.
* The buffer itself is a GPU resource, therefore mutating the data can be relatively slow.
* Typically these buffers are constant.
*
* It is possible, and even encouraged, to use a single index buffer for several Renderables.
*
* @see VertexBuffer, RenderableManager
*/
class UTILS_PUBLIC IndexBuffer : public FilamentAPI {
struct BuilderDetails;
public:
using BufferDescriptor = backend::BufferDescriptor;
/**
* Type of the index buffer
*/
enum class IndexType : uint8_t {
USHORT = uint8_t(backend::ElementType::USHORT), //!< 16-bit indices
UINT = uint8_t(backend::ElementType::UINT), //!< 32-bit indices
};
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Size of the index buffer in elements.
* @param indexCount Number of indices the IndexBuffer can hold.
* @return A reference to this Builder for chaining calls.
*/
Builder& indexCount(uint32_t indexCount) noexcept;
/**
* Type of the index buffer, 16-bit or 32-bit.
* @param indexType Type of indices stored in the IndexBuffer.
* @return A reference to this Builder for chaining calls.
*/
Builder& bufferType(IndexType indexType) noexcept;
/**
* Creates the IndexBuffer object and returns a pointer to it. After creation, the index
* buffer is uninitialized. Use IndexBuffer::setBuffer() to initialize the IndexBuffer.
*
* @param engine Reference to the filament::Engine to associate this IndexBuffer with.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*
* @see IndexBuffer::setBuffer
*/
IndexBuffer* build(Engine& engine);
private:
friend class FIndexBuffer;
};
/**
* Asynchronously copy-initializes a region of this IndexBuffer from the data provided.
*
* @param engine Reference to the filament::Engine to associate this IndexBuffer with.
* @param buffer A BufferDescriptor representing the data used to initialize the IndexBuffer.
* BufferDescriptor points to raw, untyped data that will be interpreted as
* either 16-bit or 32-bits indices based on the Type of this IndexBuffer.
* @param byteOffset Offset in *bytes* into the IndexBuffer
*/
void setBuffer(Engine& engine, BufferDescriptor&& buffer, uint32_t byteOffset = 0);
/**
* Returns the size of this IndexBuffer in elements.
* @return The number of indices the IndexBuffer holds.
*/
size_t getIndexCount() const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_INDEXBUFFER_H

349
ios/include/filament/IndirectLight.h Normal file
View File

@@ -0,0 +1,349 @@
/*
* Copyright (C) 2016 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_INDIRECT_LIGHT_H
#define TNT_FILAMENT_INDIRECT_LIGHT_H
#include <filament/FilamentAPI.h>
#include <utils/compiler.h>
#include <math/mathfwd.h>
namespace filament {
class Engine;
class Texture;
class FIndirectLight;
/**
* IndirectLight is used to simulate environment lighting, a form of global illumination.
*
* Environment lighting has a two components:
* 1. irradiance
* 2. reflections (specular component)
*
* Environments are usually captured as high-resolution HDR equirectangular images and processed
* by the **cmgen** tool to generate the data needed by IndirectLight.
*
* @note
* Currently IndirectLight is intended to be used for "distant probes", that is, to represent
* global illumination from a distant (i.e. at infinity) environment, such as the sky or distant
* mountains. Only a single IndirectLight can be used in a Scene. This limitation will be lifted
* in the future.
*
* Creation and destruction
* ========================
*
* An IndirectLight object is created using the IndirectLight::Builder and destroyed by calling
* Engine::destroy(const IndirectLight*).
*
* ~~~~~~~~~~~{.cpp}
* filament::Engine* engine = filament::Engine::create();
*
* filament::IndirectLight* environment = filament::IndirectLight::Builder()
* .reflections(cubemap)
* .build(*engine);
*
* engine->destroy(environment);
* ~~~~~~~~~~~
*
*
* Irradiance
* ==========
*
* The irradiance represents the light that comes from the environment and shines an
* object's surface.
*
* The irradiance is calculated automatically from the Reflections (see below), and generally
* doesn't need to be provided explicitly. However, it can be provided separately from the
* Reflections as
* [spherical harmonics](https://en.wikipedia.org/wiki/Spherical_harmonics) (SH) of 1, 2 or
* 3 bands, respectively 1, 4 or 9 coefficients.
*
* @note
* Use the **cmgen** tool to generate the `SH` for a given environment.
*
* Reflections
* ===========
*
* The reflections on object surfaces (specular component) is calculated from a specially
* filtered cubemap pyramid generated by the **cmgen** tool.
*
*
* @see Scene, Light, Texture, Skybox
*/
class UTILS_PUBLIC IndirectLight : public FilamentAPI {
struct BuilderDetails;
public:
//! Use Builder to construct an IndirectLight object instance
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Set the reflections cubemap mipmap chain.
*
* @param cubemap A mip-mapped cubemap generated by **cmgen**. Each cubemap level
* encodes a the irradiance for a roughness level.
*
* @return This Builder, for chaining calls.
*
*/
Builder& reflections(Texture const* cubemap) noexcept;
/**
* Sets the irradiance as Spherical Harmonics.
*
* The irradiance must be pre-convolved by \f$ \langle n \cdot l \rangle \f$ and
* pre-multiplied by the Lambertian diffuse BRDF \f$ \frac{1}{\pi} \f$ and
* specified as Spherical Harmonics coefficients.
*
* Additionally, these Spherical Harmonics coefficients must be pre-scaled by the
* reconstruction factors \f$ A_{l}^{m} \f$ below.
*
* The final coefficients can be generated using the `cmgen` tool.
*
* The index in the \p sh array is given by:
*
* `index(l, m) = l * (l + 1) + m`
*
* \f$ sh[index(l,m)] = L_{l}^{m} \frac{1}{\pi} A_{l}^{m} \hat{C_{l}} \f$
*
* index | l | m | \f$ A_{l}^{m} \f$ | \f$ \hat{C_{l}} \f$ | \f$ \frac{1}{\pi} A_{l}^{m}\hat{C_{l}} \f$ |
* :-----:|:---:|:---:|:------------------:|:---------------------:|:--------------------------------------------:
* 0 | 0 | 0 | 0.282095 | 3.1415926 | 0.282095
* 1 | 1 | -1 | -0.488602 | 2.0943951 | -0.325735
* 2 | ^ | 0 | 0.488602 | ^ | 0.325735
* 3 | ^ | 1 | -0.488602 | ^ | -0.325735
* 4 | 2 | -2 | 1.092548 | 0.785398 | 0.273137
* 5 | ^ | -1 | -1.092548 | ^ | -0.273137
* 6 | ^ | 0 | 0.315392 | ^ | 0.078848
* 7 | ^ | 1 | -1.092548 | ^ | -0.273137
* 8 | ^ | 2 | 0.546274 | ^ | 0.136569
*
*
* Only 1, 2 or 3 bands are allowed.
*
* @param bands Number of spherical harmonics bands. Must be 1, 2 or 3.
* @param sh Array containing the spherical harmonics coefficients.
* The size of the array must be \f$ bands^{2} \f$.
* (i.e. 1, 4 or 9 coefficients respectively).
*
* @return This Builder, for chaining calls.
*
* @note
* Because the coefficients are pre-scaled, `sh[0]` is the environment's
* average irradiance.
*/
Builder& irradiance(uint8_t bands, math::float3 const* sh) noexcept;
/**
* Sets the irradiance from the radiance expressed as Spherical Harmonics.
*
* The radiance must be specified as Spherical Harmonics coefficients \f$ L_{l}^{m} \f$
*
* The index in the \p sh array is given by:
*
* `index(l, m) = l * (l + 1) + m`
*
* \f$ sh[index(l,m)] = L_{l}^{m} \f$
*
* index | l | m
* :-----:|:---:|:---:
* 0 | 0 | 0
* 1 | 1 | -1
* 2 | ^ | 0
* 3 | ^ | 1
* 4 | 2 | -2
* 5 | ^ | -1
* 6 | ^ | 0
* 7 | ^ | 1
* 8 | ^ | 2
*
* @param bands Number of spherical harmonics bands. Must be 1, 2 or 3.
* @param sh Array containing the spherical harmonics coefficients.
* The size of the array must be \f$ bands^{2} \f$.
* (i.e. 1, 4 or 9 coefficients respectively).
*
* @return This Builder, for chaining calls.
*/
Builder& radiance(uint8_t bands, math::float3 const* sh) noexcept;
/**
* Sets the irradiance as a cubemap.
*
* The irradiance can alternatively be specified as a cubemap instead of Spherical
* Harmonics coefficients. It may or may not be more efficient, depending on your
* hardware (essentially, it's trading ALU for bandwidth).
*
* @param cubemap Cubemap representing the Irradiance pre-convolved by
* \f$ \langle n \cdot l \rangle \f$.
*
* @return This Builder, for chaining calls.
*
* @note
* This irradiance cubemap can be generated with the **cmgen** tool.
*
* @see irradiance(uint8_t bands, math::float3 const* sh)
*/
Builder& irradiance(Texture const* cubemap) noexcept;
/**
* (optional) Environment intensity.
*
* Because the environment is encoded usually relative to some reference, the
* range can be adjusted with this method.
*
* @param envIntensity Scale factor applied to the environment and irradiance such that
* the result is in lux, or lumen/m^2 (default = 30000)
*
* @return This Builder, for chaining calls.
*/
Builder& intensity(float envIntensity) noexcept;
/**
* Specifies the rigid-body transformation to apply to the IBL.
*
* @param rotation 3x3 rotation matrix. Must be a rigid-body transform.
*
* @return This Builder, for chaining calls.
*/
Builder& rotation(math::mat3f const& rotation) noexcept;
/**
* Creates the IndirectLight object and returns a pointer to it.
*
* @param engine Reference to the filament::Engine to associate this IndirectLight with.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*/
IndirectLight* build(Engine& engine);
private:
friend class FIndirectLight;
};
/**
* Sets the environment's intensity.
*
* Because the environment is encoded usually relative to some reference, the
* range can be adjusted with this method.
*
* @param intensity Scale factor applied to the environment and irradiance such that
* the result is in lux, or <i>lumen/m^2(default = 30000)
*/
void setIntensity(float intensity) noexcept;
/**
* Returns the environment's intensity in <i>lux</i>, or <i>lumen/m^2</i>.
*/
float getIntensity() const noexcept;
/**
* Sets the rigid-body transformation to apply to the IBL.
*
* @param rotation 3x3 rotation matrix. Must be a rigid-body transform.
*/
void setRotation(math::mat3f const& rotation) noexcept;
/**
* Returns the rigid-body transformation applied to the IBL.
*/
const math::mat3f& getRotation() const noexcept;
/**
* Returns the associated reflection map, or null if it does not exist.
*/
Texture const* getReflectionsTexture() const noexcept;
/**
* Returns the associated irradiance map, or null if it does not exist.
*/
Texture const* getIrradianceTexture() const noexcept;
/**
* Helper to estimate the direction of the dominant light in the environment represented by
* spherical harmonics.
*
* This assumes that there is only a single dominant light (such as the sun in outdoors
* environments), if it's not the case the direction returned will be an average of the
* various lights based on their intensity.
*
* If there are no clear dominant light, as is often the case with low dynamic range (LDR)
* environments, this method may return a wrong or unexpected direction.
*
* The dominant light direction can be used to set a directional light's direction,
* for instance to produce shadows that match the environment.
*
* @param sh 3-band spherical harmonics
*
* @return A unit vector representing the direction of the dominant light
*
* @see LightManager::Builder::direction()
* @see getColorEstimate()
*/
static math::float3 getDirectionEstimate(const math::float3 sh[9]) noexcept;
/**
* Helper to estimate the color and relative intensity of the environment represented by
* spherical harmonics in a given direction.
*
* This can be used to set the color and intensity of a directional light. In this case
* make sure to multiply this relative intensity by the the intensity of this indirect light.
*
* @param sh 3-band spherical harmonics
* @param direction a unit vector representing the direction of the light to estimate the
* color of. Typically this the value returned by getDirectionEstimate().
*
* @return A vector of 4 floats where the first 3 components represent the linear color and
* the 4th component represents the intensity of the dominant light
*
* @see LightManager::Builder::color()
* @see LightManager::Builder::intensity()
* @see getDirectionEstimate, getIntensity, setIntensity
*/
static math::float4 getColorEstimate(const math::float3 sh[9], math::float3 direction) noexcept;
/** @deprecated use static versions instead */
UTILS_DEPRECATED
math::float3 getDirectionEstimate() const noexcept;
/** @deprecated use static versions instead */
UTILS_DEPRECATED
math::float4 getColorEstimate(math::float3 direction) const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_INDIRECT_LIGHT_H

938
ios/include/filament/LightManager.h Normal file
View File

@@ -0,0 +1,938 @@
/*
* Copyright (C) 2017 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.
*/
#ifndef TNT_FILAMENT_LIGHTMANAGER_H
#define TNT_FILAMENT_LIGHTMANAGER_H
#include <filament/FilamentAPI.h>
#include <filament/Color.h>
#include <utils/compiler.h>
#include <utils/Entity.h>
#include <utils/EntityInstance.h>
#include <math/mathfwd.h>
namespace utils {
class Entity;
} // namespace utils
namespace filament {
class Engine;
class FEngine;
class FLightManager;
/**
* LightManager allows to create a light source in the scene, such as a sun or street lights.
*
* At least one light must be added to a scene in order to see anything
* (unless the Material.Shading.UNLIT is used).
*
*
* Creation and destruction
* ========================
*
* A Light component is created using the LightManager::Builder and destroyed by calling
* LightManager::destroy(utils::Entity).
*
* ~~~~~~~~~~~{.cpp}
* filament::Engine* engine = filament::Engine::create();
* utils::Entity sun = utils::EntityManager.get().create();
*
* filament::LightManager::Builder(Type::SUN)
* .castShadows(true)
* .build(*engine, sun);
*
* engine->getLightManager().destroy(sun);
* ~~~~~~~~~~~
*
*
* Light types
* ===========
*
* Lights come in three flavors:
* - directional lights
* - point lights
* - spot lights
*
*
* Directional lights
* ------------------
*
* Directional lights have a direction, but don't have a position. All light rays are
* parallel and come from infinitely far away and from everywhere. Typically a directional light
* is used to simulate the sun.
*
* Directional lights and spot lights are able to cast shadows.
*
* To create a directional light use Type.DIRECTIONAL or Type.SUN, both are similar, but the later
* also draws a sun's disk in the sky and its reflection on glossy objects.
*
* @warning Currently, only a single directional light is supported. If several directional lights
* are added to the scene, the dominant one will be used.
*
* @see Builder.direction(), Builder.sunAngularRadius()
*
* Point lights
* ------------
*
* Unlike directional lights, point lights have a position but emit light in all directions.
* The intensity of the light diminishes with the inverse square of the distance to the light.
* Builder.falloff() controls distance beyond which the light has no more influence.
*
* A scene can have multiple point lights.
*
* @see Builder.position(), Builder.falloff()
*
* Spot lights
* -----------
*
* Spot lights are similar to point lights but the light it emits is limited to a cone defined by
* Builder.spotLightCone() and the light's direction.
*
* A spot light is therefore defined by a position, a direction and inner and outer cones. The
* spot light's influence is limited to inside the outer cone. The inner cone defines the light's
* falloff attenuation.
*
* A physically correct spot light is a little difficult to use because changing the outer angle
* of the cone changes the illumination levels, as the same amount of light is spread over a
* changing volume. The coupling of illumination and the outer cone means that an artist cannot
* tweak the influence cone of a spot light without also changing the perceived illumination.
* It therefore makes sense to provide artists with a parameter to disable this coupling. This
* is the difference between Type.FOCUSED_SPOT and Type.SPOT.
*
* @see Builder.position(), Builder.direction(), Builder.falloff(), Builder.spotLightCone()
*
* Performance considerations
* ==========================
*
* Generally, adding lights to the scene hurts performance, however filament is designed to be
* able to handle hundreds of lights in a scene under certain conditions. Here are some tips
* to keep performances high.
*
* 1. Prefer spot lights to point lights and use the smallest outer cone angle possible.
*
* 2. Use the smallest possible falloff distance for point and spot lights.
* Performance is very sensitive to overlapping lights. The falloff distance essentially
* defines a sphere of influence for the light, so try to position point and spot lights
* such that they don't overlap too much.
*
* On the other hand, a scene can contain hundreds of non overlapping lights without
* incurring a significant overhead.
*
*/
class UTILS_PUBLIC LightManager : public FilamentAPI {
struct BuilderDetails;
public:
using Instance = utils::EntityInstance<LightManager>;
/**
* Returns the number of component in the LightManager, not that component are not
* guaranteed to be active. Use the EntityManager::isAlive() before use if needed.
*
* @return number of component in the LightManager
*/
size_t getComponentCount() const noexcept;
/**
* Returns the list of Entity for all components. Use getComponentCount() to know the size
* of the list.
* @return a pointer to Entity
*/
utils::Entity const* getEntities() const noexcept;
/**
* Returns whether a particular Entity is associated with a component of this LightManager
* @param e An Entity.
* @return true if this Entity has a component associated with this manager.
*/
bool hasComponent(utils::Entity e) const noexcept;
/**
* Gets an Instance representing the Light component associated with the given Entity.
* @param e An Entity.
* @return An Instance object, which represents the Light component associated with the Entity e.
* @note Use Instance::isValid() to make sure the component exists.
* @see hasComponent()
*/
Instance getInstance(utils::Entity e) const noexcept;
// destroys this component from the given entity
void destroy(utils::Entity e) noexcept;
//! Denotes the type of the light being created.
enum class Type : uint8_t {
SUN, //!< Directional light that also draws a sun's disk in the sky.
DIRECTIONAL, //!< Directional light, emits light in a given direction.
POINT, //!< Point light, emits light from a position, in all directions.
FOCUSED_SPOT, //!< Physically correct spot light.
SPOT, //!< Spot light with coupling of outer cone and illumination disabled.
};
/**
* Control the quality / performance of the shadow map associated to this light
*/
struct ShadowOptions {
/** Size of the shadow map in texels. Must be a power-of-two and larger or equal to 8. */
uint32_t mapSize = 1024;
/**
* Number of shadow cascades to use for this light. Must be between 1 and 4 (inclusive).
* A value greater than 1 turns on cascaded shadow mapping (CSM).
* Only applicable to Type.SUN or Type.DIRECTIONAL lights.
*
* When using shadow cascades, cascadeSplitPositions must also be set.
*
* @see ShadowOptions::cascadeSplitPositions
*/
uint8_t shadowCascades = 1;
/**
* The split positions for shadow cascades.
*
* Cascaded shadow mapping (CSM) partitions the camera frustum into cascades. These values
* determine the planes along the camera's Z axis to split the frustum. The camera near
* plane is represented by 0.0f and the far plane represented by 1.0f.
*
* For example, if using 4 cascades, these values would set a uniform split scheme:
* { 0.25f, 0.50f, 0.75f }
*
* For N cascades, N - 1 split positions will be read from this array.
*
* Filament provides utility methods inside LightManager::ShadowCascades to help set these
* values. For example, to use a uniform split scheme:
*
* ~~~~~~~~~~~{.cpp}
* LightManager::ShadowCascades::computeUniformSplits(options.splitPositions, 4);
* ~~~~~~~~~~~
*
* @see ShadowCascades::computeUniformSplits
* @see ShadowCascades::computeLogSplits
* @see ShadowCascades::computePracticalSplits
*/
float cascadeSplitPositions[3] = { 0.25f, 0.50f, 0.75f };
/** Constant bias in world units (e.g. meters) by which shadows are moved away from the
* light. 1mm by default.
* This is ignored when the View's ShadowType is set to VSM.
*/
float constantBias = 0.001f;
/** Amount by which the maximum sampling error is scaled. The resulting value is used
* to move the shadow away from the fragment normal. Should be 1.0.
* This is ignored when the View's ShadowType is set to VSM.
*/
float normalBias = 1.0f;
/** Distance from the camera after which shadows are clipped. This is used to clip
* shadows that are too far and wouldn't contribute to the scene much, improving
* performance and quality. This value is always positive.
* Use 0.0f to use the camera far distance.
*/
float shadowFar = 0.0f;
/** Optimize the quality of shadows from this distance from the camera. Shadows will
* be rendered in front of this distance, but the quality may not be optimal.
* This value is always positive. Use 0.0f to use the camera near distance.
* The default of 1m works well with many scenes. The quality of shadows may drop
* rapidly when this value decreases.
*/
float shadowNearHint = 1.0f;
/** Optimize the quality of shadows in front of this distance from the camera. Shadows
* will be rendered behind this distance, but the quality may not be optimal.
* This value is always positive. Use std::numerical_limits<float>::infinity() to
* use the camera far distance.
*/
float shadowFarHint = 100.0f;
/**
* Controls whether the shadow map should be optimized for resolution or stability.
* When set to true, all resolution enhancing features that can affect stability are
* disabling, resulting in significantly lower resolution shadows, albeit stable ones.
*/
bool stable = false;
/**
* Constant bias in depth-resolution units by which shadows are moved away from the
* light. The default value of 0.5 is used to round depth values up.
* Generally this value shouldn't be changed or at least be small and positive.
*/
float polygonOffsetConstant = 0.5f;
/**
* Bias based on the change in depth in depth-resolution units by which shadows are moved
* away from the light. The default value of 2.0 works well with SHADOW_SAMPLING_PCF_LOW.
* Generally this value is between 0.5 and the size in texel of the PCF filter.
* Setting this value correctly is essential for LISPSM shadow-maps.
*/
float polygonOffsetSlope = 2.0f;
/**
* Whether screen-space contact shadows are used. This applies regardless of whether a
* Renderable is a shadow caster.
* Screen-space contact shadows are typically useful in large scenes.
* (off by default)
*/
bool screenSpaceContactShadows = false;
/**
* Number of ray-marching steps for screen-space contact shadows (8 by default).
*
* CAUTION: this parameter is ignored for all lights except the directional/sun light,
* all other lights use the same value set for the directional/sun light.
*
*/
uint8_t stepCount = 8;
/**
* Maximum shadow-occluder distance for screen-space contact shadows (world units).
* (30 cm by default)
*
* CAUTION: this parameter is ignored for all lights except the directional/sun light,
* all other lights use the same value set for the directional/sun light.
*
*/
float maxShadowDistance = 0.3f;
/**
* Options available when the View's ShadowType is set to VSM.
*
* @warning This API is still experimental and subject to change.
* @see View::setShadowType
*/
struct Vsm {
/**
* The number of MSAA samples to use when rendering VSM shadow maps.
* Must be a power-of-two and greater than or equal to 1. A value of 1 effectively turns
* off MSAA.
* Higher values may not be available depending on the underlying hardware.
*/
uint8_t msaaSamples = 1;
/**
* Blur width for the VSM blur. Zero do disable.
* The maximum value is 125.
*/
float blurWidth = 0.0f;
} vsm;
};
struct ShadowCascades {
/**
* Utility method to compute ShadowOptions::cascadeSplitPositions according to a uniform
* split scheme.
*
* @param splitPositions a float array of at least size (cascades - 1) to write the split
* positions into
* @param cascades the number of shadow cascades, at most 4
*/
static void computeUniformSplits(float* splitPositions, uint8_t cascades);
/**
* Utility method to compute ShadowOptions::cascadeSplitPositions according to a logarithmic
* split scheme.
*
* @param splitPositions a float array of at least size (cascades - 1) to write the split
* positions into
* @param cascades the number of shadow cascades, at most 4
* @param near the camera near plane
* @param far the camera far plane
*/
static void computeLogSplits(float* splitPositions, uint8_t cascades,
float near, float far);
/**
* Utility method to compute ShadowOptions::cascadeSplitPositions according to a practical
* split scheme.
*
* The practical split scheme uses uses a lambda value to interpolate between the logarithmic
* and uniform split schemes. Start with a lambda value of 0.5f and adjust for your scene.
*
* See: Zhang et al 2006, "Parallel-split shadow maps for large-scale virtual environments"
*
* @param splitPositions a float array of at least size (cascades - 1) to write the split
* positions into
* @param cascades the number of shadow cascades, at most 4
* @param near the camera near plane
* @param far the camera far plane
* @param lambda a float in the range [0, 1] that interpolates between log and
* uniform split schemes
*/
static void computePracticalSplits(float* splitPositions, uint8_t cascades,
float near, float far, float lambda);
};
//! Use Builder to construct a Light object instance
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
/**
* Creates a light builder and set the light's #Type.
*
* @param type #Type of Light object to create.
*/
explicit Builder(Type type) noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Enables or disables a light channel. Light channel 0 is enabled by default.
*
* @param channel Light channel to enable or disable, between 0 and 7.
* @param enable Whether to enable or disable the light channel.
* @return This Builder, for chaining calls.
*/
Builder& lightChannel(unsigned int channel, bool enable = true) noexcept;
/**
* Whether this Light casts shadows (disabled by default)
*
* @param enable Enables or disables casting shadows from this Light.
*
* @return This Builder, for chaining calls.
*
* @warning
* - Only a Type.DIRECTIONAL, Type.SUN, Type.SPOT, or Type.FOCUSED_SPOT light can cast shadows
*/
Builder& castShadows(bool enable) noexcept;
/**
* Sets the shadow-map options for this light.
*
* @return This Builder, for chaining calls.
*/
Builder& shadowOptions(const ShadowOptions& options) noexcept;
/**
* Whether this light casts light (enabled by default)
*
* @param enable Enables or disables lighting from this Light.
*
* @return This Builder, for chaining calls.
*
* @note
* In some situations it can be useful to have a light in the scene that doesn't
* actually emit light, but does cast shadows.
*/
Builder& castLight(bool enable) noexcept;
/**
* Sets the initial position of the light in world space.
*
* @param position Light's position in world space. The default is at the origin.
*
* @return This Builder, for chaining calls.
*
* @note
* The Light's position is ignored for directional lights (Type.DIRECTIONAL or Type.SUN)
*/
Builder& position(const math::float3& position) noexcept;
/**
* Sets the initial direction of a light in world space.
*
* @param direction Light's direction in world space. Should be a unit vector.
* The default is {0,-1,0}.
*
* @return This Builder, for chaining calls.
*
* @note
* The Light's direction is ignored for Type.POINT lights.
*/
Builder& direction(const math::float3& direction) noexcept;
/**
* Sets the initial color of a light.
*
* @param color Color of the light specified in the linear sRGB color-space.
* The default is white {1,1,1}.
*
* @return This Builder, for chaining calls.
*/
Builder& color(const LinearColor& color) noexcept;
/**
* Sets the initial intensity of a light.
* @param intensity This parameter depends on the Light.Type:
* - For directional lights, it specifies the illuminance in *lux*
* (or *lumen/m^2*).
* - For point lights and spot lights, it specifies the luminous power
* in *lumen*.
*
* @return This Builder, for chaining calls.
*
* For example, the sun's illuminance is about 100,000 lux.
*
* This method overrides any prior calls to intensity or intensityCandela.
*
*/
Builder& intensity(float intensity) noexcept;
/**
* Sets the initial intensity of a spot or point light in candela.
*
* @param intensity Luminous intensity in *candela*.
*
* @return This Builder, for chaining calls.
*
* @note
* This method is equivalent to calling intensity(float intensity) for directional lights
* (Type.DIRECTIONAL or Type.SUN).
*
* This method overrides any prior calls to intensity or intensityCandela.
*/
Builder& intensityCandela(float intensity) noexcept;
/**
* Sets the initial intensity of a light in watts.
*
* @param watts Energy consumed by a lightbulb. It is related to the energy produced
* and ultimately the brightness by the \p efficiency parameter.
* This value is often available on the packaging of commercial
* lightbulbs.
*
* @param efficiency Efficiency in percent. This depends on the type of lightbulb used.
*
* Lightbulb type | Efficiency
* ----------------:|-----------:
* Incandescent | 2.2%
* Halogen | 7.0%
* LED | 8.7%
* Fluorescent | 10.7%
*
* @return This Builder, for chaining calls.
*
*
* @note
* This call is equivalent to `Builder::intensity(efficiency * 683 * watts);`
*
* This method overrides any prior calls to intensity or intensityCandela.
*/
Builder& intensity(float watts, float efficiency) noexcept;
/**
* Set the falloff distance for point lights and spot lights.
*
* At the falloff distance, the light has no more effect on objects.
*
* The falloff distance essentially defines a *sphere of influence* around the light, and
* therefore has an impact on performance. Larger falloffs might reduce performance
* significantly, especially when many lights are used.
*
* Try to avoid having a large number of light's spheres of influence overlap.
*
* @param radius Falloff distance in world units. Default is 1 meter.
*
* @return This Builder, for chaining calls.
*
* @note
* The Light's falloff is ignored for directional lights (Type.DIRECTIONAL or Type.SUN)
*/
Builder& falloff(float radius) noexcept;
/**
* Defines a spot light'st angular falloff attenuation.
*
* A spot light is defined by a position, a direction and two cones, \p inner and \p outer.
* These two cones are used to define the angular falloff attenuation of the spot light
* and are defined by the angle from the center axis to where the falloff begins (i.e.
* cones are defined by their half-angle).
*
* @param inner inner cone angle in *radians* between 0 and @f$ \pi/2 @f$
*
* @param outer outer cone angle in *radians* between \p inner and @f$ \pi/2 @f$
*
* @return This Builder, for chaining calls.
*
* @note
* The spot light cone is ignored for directional and point lights.
*
* @see Type.SPOT, Type.FOCUSED_SPOT
*/
Builder& spotLightCone(float inner, float outer) noexcept;
/**
* Defines the angular radius of the sun, in degrees, between 0.25° and 20.0°
*
* The Sun as seen from Earth has an angular size of 0.526° to 0.545°
*
* @param angularRadius sun's radius in degree. Default is 0.545°.
*
* @return This Builder, for chaining calls.
*/
Builder& sunAngularRadius(float angularRadius) noexcept;
/**
* Defines the halo radius of the sun. The radius of the halo is defined as a
* multiplier of the sun angular radius.
*
* @param haloSize radius multiplier. Default is 10.0.
*
* @return This Builder, for chaining calls.
*/
Builder& sunHaloSize(float haloSize) noexcept;
/**
* Defines the halo falloff of the sun. The falloff is a dimensionless number
* used as an exponent.
*
* @param haloFalloff halo falloff. Default is 80.0.
*
* @return This Builder, for chaining calls.
*/
Builder& sunHaloFalloff(float haloFalloff) noexcept;
enum Result { Error = -1, Success = 0 };
/**
* Adds the Light component to an entity.
*
* @param engine Reference to the filament::Engine to associate this light with.
* @param entity Entity to add the light component to.
* @return Success if the component was created successfully, Error otherwise.
*
* If exceptions are disabled and an error occurs, this function is a no-op.
* Success can be checked by looking at the return value.
*
* If this component already exists on the given entity, it is first destroyed as if
* destroy(utils::Entity e) was called.
*
* @warning
* Currently, only 2048 lights can be created on a given Engine.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*/
Result build(Engine& engine, utils::Entity entity);
private:
friend class FEngine;
friend class FLightManager;
};
static constexpr float EFFICIENCY_INCANDESCENT = 0.0220f; //!< Typical efficiency of an incandescent light bulb (2.2%)
static constexpr float EFFICIENCY_HALOGEN = 0.0707f; //!< Typical efficiency of an halogen light bulb (7.0%)
static constexpr float EFFICIENCY_FLUORESCENT = 0.0878f; //!< Typical efficiency of a fluorescent light bulb (8.7%)
static constexpr float EFFICIENCY_LED = 0.1171f; //!< Typical efficiency of a LED light bulb (11.7%)
Type getType(Instance i) const noexcept;
/**
* Helper function that returns if a light is a directional light
*
* @param i Instance of the component obtained from getInstance().
* @return true is this light is a type of directional light
*/
inline bool isDirectional(Instance i) const noexcept {
Type type = getType(i);
return type == Type::DIRECTIONAL || type == Type::SUN;
}
/**
* Helper function that returns if a light is a point light
*
* @param i Instance of the component obtained from getInstance().
* @return true is this light is a type of point light
*/
inline bool isPointLight(Instance i) const noexcept {
return getType(i) == Type::POINT;
}
/**
* Helper function that returns if a light is a spot light
*
* @param i Instance of the component obtained from getInstance().
* @return true is this light is a type of spot light
*/
inline bool isSpotLight(Instance i) const noexcept {
Type type = getType(i);
return type == Type::SPOT || type == Type::FOCUSED_SPOT;
}
/**
* Enables or disables a light channel. Light channel 0 is enabled by default.
* @param channel light channel to enable or disable, between 0 and 7.
* @param enable whether to enable (true) or disable (false) the specified light channel.
*/
void setLightChannel(Instance i, unsigned int channel, bool enable = true) noexcept;
/**
* Returns whether a light channel is enabled on a specified light.
* @param i Instance of the component obtained from getInstance().
* @param channel Light channel to query
* @return true if the light channel is enabled, false otherwise
*/
bool getLightChannel(Instance i, unsigned int channel) const noexcept;
/**
* Dynamically updates the light's position.
*
* @param i Instance of the component obtained from getInstance().
* @param position Light's position in world space. The default is at the origin.
*
* @see Builder.position()
*/
void setPosition(Instance i, const math::float3& position) noexcept;
//! returns the light's position in world space
const math::float3& getPosition(Instance i) const noexcept;
/**
* Dynamically updates the light's direction
*
* @param i Instance of the component obtained from getInstance().
* @param direction Light's direction in world space. Should be a unit vector.
* The default is {0,-1,0}.
*
* @see Builder.direction()
*/
void setDirection(Instance i, const math::float3& direction) noexcept;
//! returns the light's direction in world space
const math::float3& getDirection(Instance i) const noexcept;
/**
* Dynamically updates the light's hue as linear sRGB
*
* @param i Instance of the component obtained from getInstance().
* @param color Color of the light specified in the linear sRGB color-space.
* The default is white {1,1,1}.
*
* @see Builder.color(), getInstance()
*/
void setColor(Instance i, const LinearColor& color) noexcept;
/**
* @param i Instance of the component obtained from getInstance().
* @return the light's color in linear sRGB
*/
const math::float3& getColor(Instance i) const noexcept;
/**
* Dynamically updates the light's intensity. The intensity can be negative.
*
* @param i Instance of the component obtained from getInstance().
* @param intensity This parameter depends on the Light.Type:
* - For directional lights, it specifies the illuminance in *lux*
* (or *lumen/m^2*).
* - For point lights and spot lights, it specifies the luminous power
* in *lumen*.
*
* @see Builder.intensity()
*/
void setIntensity(Instance i, float intensity) noexcept;
/**
* Dynamically updates the light's intensity. The intensity can be negative.
*
* @param i Instance of the component obtained from getInstance().
* @param watts Energy consumed by a lightbulb. It is related to the energy produced
* and ultimately the brightness by the \p efficiency parameter.
* This value is often available on the packaging of commercial
* lightbulbs.
* @param efficiency Efficiency in percent. This depends on the type of lightbulb used.
*
* Lightbulb type | Efficiency
* ----------------:|-----------:
* Incandescent | 2.2%
* Halogen | 7.0%
* LED | 8.7%
* Fluorescent | 10.7%
*
* @see Builder.intensity(float watts, float efficiency)
*/
void setIntensity(Instance i, float watts, float efficiency) noexcept {
setIntensity(i, watts * 683.0f * efficiency);
}
/**
* Dynamically updates the light's intensity in candela. The intensity can be negative.
*
* @param i Instance of the component obtained from getInstance().
* @param intensity Luminous intensity in *candela*.
*
* @note
* This method is equivalent to calling setIntensity(float intensity) for directional lights
* (Type.DIRECTIONAL or Type.SUN).
*
* @see Builder.intensityCandela(float intensity)
*/
void setIntensityCandela(Instance i, float intensity) noexcept;
/**
* returns the light's luminous intensity in candela.
*
* @param i Instance of the component obtained from getInstance().
*
* @note for Type.FOCUSED_SPOT lights, the returned value depends on the \p outer cone angle.
*
* @return luminous intensity in candela.
*/
float getIntensity(Instance i) const noexcept;
/**
* Set the falloff distance for point lights and spot lights.
*
* @param i Instance of the component obtained from getInstance().
* @param radius falloff distance in world units. Default is 1 meter.
*
* @see Builder.falloff()
*/
void setFalloff(Instance i, float radius) noexcept;
/**
* returns the falloff distance of this light.
* @param i Instance of the component obtained from getInstance().
* @return the falloff distance of this light.
*/
float getFalloff(Instance i) const noexcept;
/**
* Dynamically updates a spot light's cone as angles
*
* @param i Instance of the component obtained from getInstance().
* @param inner inner cone angle in *radians* between 0 and pi/2
* @param outer outer cone angle in *radians* between inner and pi/2
*
* @see Builder.spotLightCone()
*/
void setSpotLightCone(Instance i, float inner, float outer) noexcept;
/**
* returns the outer cone angle in *radians* between inner and pi/2.
* @param i Instance of the component obtained from getInstance().
* @return the outer cone angle of this light.
*/
float getSpotLightOuterCone(Instance i) const noexcept;
/**
* returns the inner cone angle in *radians* between 0 and pi/2.
*
* The value is recomputed from the initial values, thus is not precisely
* the same as the one passed to setSpotLightCone() or Builder.spotLightCone().
*
* @param i Instance of the component obtained from getInstance().
* @return the inner cone angle of this light.
*/
float getSpotLightInnerCone(Instance i) const noexcept;
/**
* Dynamically updates the angular radius of a Type.SUN light
*
* The Sun as seen from Earth has an angular size of 0.526° to 0.545°
*
* @param i Instance of the component obtained from getInstance().
* @param angularRadius sun's radius in degrees. Default is 0.545°.
*/
void setSunAngularRadius(Instance i, float angularRadius) noexcept;
/**
* returns the angular radius if the sun in degrees.
* @param i Instance of the component obtained from getInstance().
* @return the angular radius if the sun in degrees.
*/
float getSunAngularRadius(Instance i) const noexcept;
/**
* Dynamically updates the halo radius of a Type.SUN light. The radius
* of the halo is defined as a multiplier of the sun angular radius.
*
* @param i Instance of the component obtained from getInstance().
* @param haloSize radius multiplier. Default is 10.0.
*/
void setSunHaloSize(Instance i, float haloSize) noexcept;
/**
* returns the halo size of a Type.SUN light as a multiplier of the
* sun angular radius.
* @param i Instance of the component obtained from getInstance().
* @return the halo size
*/
float getSunHaloSize(Instance i) const noexcept;
/**
* Dynamically updates the halo falloff of a Type.SUN light. The falloff
* is a dimensionless number used as an exponent.
*
* @param i Instance of the component obtained from getInstance().
* @param haloFalloff halo falloff. Default is 80.0.
*/
void setSunHaloFalloff(Instance i, float haloFalloff) noexcept;
/**
* returns the halo falloff of a Type.SUN light as a dimensionless value.
* @param i Instance of the component obtained from getInstance().
* @return the halo falloff
*/
float getSunHaloFalloff(Instance i) const noexcept;
/**
* returns the shadow-map options for a given light
* @param i Instance of the component obtained from getInstance().
* @return A ShadowOption structure
*/
ShadowOptions const& getShadowOptions(Instance i) const noexcept;
/**
* sets the shadow-map options for a given light
* @param i Instance of the component obtained from getInstance().
* @param options A ShadowOption structure
*/
void setShadowOptions(Instance i, ShadowOptions const& options) noexcept;
/**
* Whether this Light casts shadows (disabled by default)
*
* @param i Instance of the component obtained from getInstance().
* @param shadowCaster Enables or disables casting shadows from this Light.
*
* @warning
* - Only a Type.DIRECTIONAL, Type.SUN, Type.SPOT, or Type.FOCUSED_SPOT light can cast shadows
*/
void setShadowCaster(Instance i, bool shadowCaster) noexcept;
/**
* returns whether this light casts shadows.
* @param i Instance of the component obtained from getInstance().
*/
bool isShadowCaster(Instance i) const noexcept;
/**
* Helper to process all components with a given function
* @tparam F a void(Entity entity, Instance instance)
* @param func a function of type F
*/
template<typename F>
void forEachComponent(F func) noexcept {
utils::Entity const* const pEntity = getEntities();
for (size_t i = 0, c = getComponentCount(); i < c; i++) {
// Instance 0 is the invalid instance
func(pEntity[i], Instance(i + 1));
}
}
};
} // namespace filament
#endif // TNT_FILAMENT_LIGHTMANAGER_H

284
ios/include/filament/Material.h Normal file
View File

@@ -0,0 +1,284 @@
/*
* 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.
*/
#ifndef TNT_FILAMENT_MATERIAL_H
#define TNT_FILAMENT_MATERIAL_H
#include <filament/Color.h>
#include <filament/FilamentAPI.h>
#include <filament/MaterialEnums.h>
#include <filament/MaterialInstance.h>
#include <backend/DriverEnums.h>
#include <utils/compiler.h>
#include <math/mathfwd.h>
#include <stdint.h>
namespace utils {
class CString;
} // namespace utils
namespace filament {
class Texture;
class TextureSampler;
class FEngine;
class FMaterial;
class Engine;
class UTILS_PUBLIC Material : public FilamentAPI {
struct BuilderDetails;
public:
using BlendingMode = BlendingMode;
using Shading = Shading;
using Interpolation = Interpolation;
using VertexDomain = VertexDomain;
using TransparencyMode = TransparencyMode;
using ParameterType = backend::UniformType;
using Precision = backend::Precision;
using SamplerType = backend::SamplerType;
using SamplerFormat = backend::SamplerFormat;
using CullingMode = backend::CullingMode;
using ShaderModel = backend::ShaderModel;
using SubpassType = backend::SubpassType;
/**
* Holds information about a material parameter.
*/
struct ParameterInfo {
//! Name of the parameter.
const char* name;
//! Whether the parameter is a sampler (texture).
bool isSampler;
//! Whether the parameter is a subpass type.
bool isSubpass;
union {
//! Type of the parameter if the parameter is not a sampler.
ParameterType type;
//! Type of the parameter if the parameter is a sampler.
SamplerType samplerType;
//! Type of the parameter if the parameter is a subpass.
SubpassType subpassType;
};
//! Size of the parameter when the parameter is an array.
uint32_t count;
//! Requested precision of the parameter.
Precision precision;
};
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Specifies the material data. The material data is a binary blob produced by
* libfilamat or by matc.
*
* @param payload Pointer to the material data, must stay valid until build() is called.
* @param size Size of the material data pointed to by "payload" in bytes.
*/
Builder& package(const void* payload, size_t size);
/**
* Creates the Material object and returns a pointer to it.
*
* @param engine Reference to the filament::Engine to associate this Material with.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*/
Material* build(Engine& engine);
private:
friend class FMaterial;
};
/**
* Creates a new instance of this material. Material instances should be freed using
* Engine::destroy(const MaterialInstance*).
*
* @param name Optional name to associate with the given material instance. If this is null,
* then the instance inherits the material's name.
*
* @return A pointer to the new instance.
*/
MaterialInstance* createInstance(const char* name = nullptr) const noexcept;
//! Returns the name of this material as a null-terminated string.
const char* getName() const noexcept;
//! Returns the shading model of this material.
Shading getShading() const noexcept;
//! Returns the interpolation mode of this material. This affects how variables are interpolated.
Interpolation getInterpolation() const noexcept;
//! Returns the blending mode of this material.
BlendingMode getBlendingMode() const noexcept;
//! Returns the vertex domain of this material.
VertexDomain getVertexDomain() const noexcept;
//! Returns the material domain of this material.
//! The material domain determines how the material is used.
MaterialDomain getMaterialDomain() const noexcept;
//! Returns the default culling mode of this material.
CullingMode getCullingMode() const noexcept;
//! Returns the transparency mode of this material.
//! This value only makes sense when the blending mode is transparent or fade.
TransparencyMode getTransparencyMode() const noexcept;
//! Indicates whether instances of this material will, by default, write to the color buffer.
bool isColorWriteEnabled() const noexcept;
//! Indicates whether instances of this material will, by default, write to the depth buffer.
bool isDepthWriteEnabled() const noexcept;
//! Indicates whether instances of this material will, by default, use depth testing.
bool isDepthCullingEnabled() const noexcept;
//! Indicates whether this material is double-sided.
bool isDoubleSided() const noexcept;
//! Returns the alpha mask threshold used when the blending mode is set to masked.
float getMaskThreshold() const noexcept;
//! Indicates whether this material uses the shadowing factor as a color multiplier.
//! This values only makes sense when the shading mode is unlit.
bool hasShadowMultiplier() const noexcept;
//! Indicates whether this material has specular anti-aliasing enabled
bool hasSpecularAntiAliasing() const noexcept;
//! Returns the screen-space variance for specular-antialiasing, this value is between 0 and 1.
float getSpecularAntiAliasingVariance() const noexcept;
//! Returns the clamping threshold for specular-antialiasing, this value is between 0 and 1.
float getSpecularAntiAliasingThreshold() const noexcept;
//! Returns the list of vertex attributes required by this material.
AttributeBitset getRequiredAttributes() const noexcept;
//! Returns the refraction mode used by this material.
RefractionMode getRefractionMode() const noexcept;
// Return the refraction type used by this material.
RefractionType getRefractionType() const noexcept;
/**
* Returns the number of parameters declared by this material.
* The returned value can be 0.
*/
size_t getParameterCount() const noexcept;
/**
* Gets information about this material's parameters.
*
* @param parameters A pointer to a list of ParameterInfo.
* The list must be at least "count" large
* @param count The number of parameters to retrieve. Must be >= 0 and can be > count.
*
* @return The number of parameters written to the parameters pointer.
*/
size_t getParameters(ParameterInfo* parameters, size_t count) const noexcept;
//! Indicates whether a parameter of the given name exists on this material.
bool hasParameter(const char* name) const noexcept;
//! Indicates whether an existing parameter is a sampler or not.
bool isSampler(const char* name) const noexcept;
/**
* Sets the value of the given parameter on this material's default instance.
*
* @param name The name of the material parameter
* @param value The value of the material parameter
*
* @see getDefaultInstance()
*/
template <typename T>
void setDefaultParameter(const char* name, T value) noexcept {
getDefaultInstance()->setParameter(name, value);
}
/**
* Sets a texture and sampler parameters on this material's default instance.
*
* @param name The name of the material texture parameter
* @param texture The texture to set as parameter
* @param sampler The sampler to be used with this texture
*
* @see getDefaultInstance()
*/
void setDefaultParameter(const char* name, Texture const* texture,
TextureSampler const& sampler) noexcept {
getDefaultInstance()->setParameter(name, texture, sampler);
}
/**
* Sets the color of the given parameter on this material's default instance.
*
* @param name The name of the material color parameter
* @param type Whether the color is specified in the linear or sRGB space
* @param color The color as a floating point red, green, blue tuple
*
* @see getDefaultInstance()
*/
void setDefaultParameter(const char* name, RgbType type, math::float3 color) noexcept {
getDefaultInstance()->setParameter(name, type, color);
}
/**
* Sets the color of the given parameter on this material's default instance.
*
* @param name The name of the material color parameter
* @param type Whether the color is specified in the linear or sRGB space
* @param color The color as a floating point red, green, blue, alpha tuple
*
* @see getDefaultInstance()
*/
void setDefaultParameter(const char* name, RgbaType type, math::float4 color) noexcept {
getDefaultInstance()->setParameter(name, type, color);
}
//! Returns this material's default instance.
MaterialInstance* getDefaultInstance() noexcept;
//! Returns this material's default instance.
MaterialInstance const* getDefaultInstance() const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_MATERIAL_H

87
ios/include/filament/MaterialChunkType.h Normal file
View File

@@ -0,0 +1,87 @@
/*
* Copyright (C) 2017 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.
*/
#ifndef TNT_FILAMAT_MATERIAL_CHUNK_TYPES_H
#define TNT_FILAMAT_MATERIAL_CHUNK_TYPES_H
#include <stdint.h>
#include <utils/compiler.h>
namespace filamat {
// Pack an eight character string into a 64 bit integer.
constexpr inline uint64_t charTo64bitNum(const char str[9]) noexcept {
return
( (static_cast<uint64_t >(str[0]) << 56))
| ((static_cast<uint64_t >(str[1]) << 48) & 0x00FF000000000000U)
| ((static_cast<uint64_t >(str[2]) << 40) & 0x0000FF0000000000U)
| ((static_cast<uint64_t >(str[3]) << 32) & 0x000000FF00000000U)
| ((static_cast<uint64_t >(str[4]) << 24) & 0x00000000FF000000U)
| ((static_cast<uint64_t >(str[5]) << 16) & 0x0000000000FF0000U)
| ((static_cast<uint64_t >(str[6]) << 8) & 0x000000000000FF00U)
| ( static_cast<uint64_t >(str[7]) & 0x00000000000000FFU);
}
enum UTILS_PUBLIC ChunkType : uint64_t {
Unknown = charTo64bitNum("UNKNOWN "),
MaterialUib = charTo64bitNum("MAT_UIB "),
MaterialSib = charTo64bitNum("MAT_SIB "),
MaterialSubpass = charTo64bitNum("MAT_SUB "),
MaterialGlsl = charTo64bitNum("MAT_GLSL"),
MaterialSpirv = charTo64bitNum("MAT_SPIR"),
MaterialMetal = charTo64bitNum("MAT_METL"),
MaterialShaderModels = charTo64bitNum("MAT_SMDL"),
MaterialSamplerBindings = charTo64bitNum("MAT_SAMP"), // no longer used
MaterialProperties = charTo64bitNum("MAT_PROP"),
MaterialName = charTo64bitNum("MAT_NAME"),
MaterialVersion = charTo64bitNum("MAT_VERS"),
MaterialShading = charTo64bitNum("MAT_SHAD"),
MaterialBlendingMode = charTo64bitNum("MAT_BLEN"),
MaterialTransparencyMode = charTo64bitNum("MAT_TRMD"),
MaterialMaskThreshold = charTo64bitNum("MAT_THRS"),
MaterialShadowMultiplier = charTo64bitNum("MAT_SHML"),
MaterialSpecularAntiAliasing = charTo64bitNum("MAT_SPAA"),
MaterialSpecularAntiAliasingVariance = charTo64bitNum("MAT_SVAR"),
MaterialSpecularAntiAliasingThreshold = charTo64bitNum("MAT_STHR"),
MaterialClearCoatIorChange = charTo64bitNum("MAT_CIOR"),
MaterialDomain = charTo64bitNum("MAT_DOMN"),
MaterialRefraction = charTo64bitNum("MAT_REFM"),
MaterialRefractionType = charTo64bitNum("MAT_REFT"),
MaterialRequiredAttributes = charTo64bitNum("MAT_REQA"),
MaterialDepthWriteSet = charTo64bitNum("MAT_DEWS"),
MaterialDoubleSidedSet = charTo64bitNum("MAT_DOSS"),
MaterialDoubleSided = charTo64bitNum("MAT_DOSI"),
MaterialColorWrite = charTo64bitNum("MAT_CWRIT"),
MaterialDepthWrite = charTo64bitNum("MAT_DWRIT"),
MaterialDepthTest = charTo64bitNum("MAT_DTEST"),
MaterialCullingMode = charTo64bitNum("MAT_CUMO"),
MaterialHasCustomDepthShader =charTo64bitNum("MAT_CSDP"),
MaterialVertexDomain = charTo64bitNum("MAT_VEDO"),
MaterialInterpolation = charTo64bitNum("MAT_INTR"),
DictionaryText = charTo64bitNum("DIC_TEXT"),
DictionarySpirv = charTo64bitNum("DIC_SPIR"),
};
} // namespace filamat
#endif // TNT_FILAMAT_MATERIAL_CHUNK_TYPES_H

226
ios/include/filament/MaterialEnums.h Normal file
View File

@@ -0,0 +1,226 @@
/*
* 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_MATERIAL_ENUM_H
#define TNT_FILAMENT_MATERIAL_ENUM_H
#include <utils/bitset.h>
#include <stddef.h>
#include <stdint.h>
namespace filament {
// update this when a new version of filament wouldn't work with older materials
static constexpr size_t MATERIAL_VERSION = 12;
/**
* Supported shading models
*/
enum class Shading : uint8_t {
UNLIT, //!< no lighting applied, emissive possible
LIT, //!< default, standard lighting
SUBSURFACE, //!< subsurface lighting model
CLOTH, //!< cloth lighting model
SPECULAR_GLOSSINESS, //!< legacy lighting model
};
/**
* Attribute interpolation types in the fragment shader
*/
enum class Interpolation : uint8_t {
SMOOTH, //!< default, smooth interpolation
FLAT //!< flat interpolation
};
/**
* Shader quality, affect some global quality parameters
*/
enum class ShaderQuality : int8_t {
DEFAULT = -1, // LOW on mobile, HIGH on desktop
LOW = 0, // enable optimizations that can slightly affect correctness
NORMAL = 1, // normal quality, correctness honored
HIGH = 2 // higher quality (e.g. better upscaling, etc...)
};
/**
* Supported blending modes
*/
enum class BlendingMode : uint8_t {
//! material is opaque
OPAQUE,
//! material is transparent and color is alpha-pre-multiplied, affects diffuse lighting only
TRANSPARENT,
//! material is additive (e.g.: hologram)
ADD,
//! material is masked (i.e. alpha tested)
MASKED,
/**
* material is transparent and color is alpha-pre-multiplied, affects specular lighting
* when adding more entries, change the size of FRenderer::CommandKey::blending
*/
FADE,
//! material darkens what's behind it
MULTIPLY,
//! material brightens what's behind it
SCREEN,
};
/**
* How transparent objects are handled
*/
enum class TransparencyMode : uint8_t {
//! the transparent object is drawn honoring the raster state
DEFAULT,
/**
* the transparent object is first drawn in the depth buffer,
* then in the color buffer, honoring the culling mode, but ignoring the depth test function
*/
TWO_PASSES_ONE_SIDE,
/**
* the transparent object is drawn twice in the color buffer,
* first with back faces only, then with front faces; the culling
* mode is ignored. Can be combined with two-sided lighting
*/
TWO_PASSES_TWO_SIDES
};
/**
* Supported types of vertex domains.
*/
enum class VertexDomain : uint8_t {
OBJECT, //!< vertices are in object space, default
WORLD, //!< vertices are in world space
VIEW, //!< vertices are in view space
DEVICE //!< vertices are in normalized device space
// when adding more entries, make sure to update VERTEX_DOMAIN_COUNT
};
/**
* Vertex attribute types
*/
enum VertexAttribute : uint8_t {
// Update hasIntegerTarget() in VertexBuffer when adding an attribute that will
// be read as integers in the shaders
POSITION = 0, //!< XYZ position (float3)
TANGENTS = 1, //!< tangent, bitangent and normal, encoded as a quaternion (float4)
COLOR = 2, //!< vertex color (float4)
UV0 = 3, //!< texture coordinates (float2)
UV1 = 4, //!< texture coordinates (float2)
BONE_INDICES = 5, //!< indices of 4 bones, as unsigned integers (uvec4)
BONE_WEIGHTS = 6, //!< weights of the 4 bones (normalized float4)
// -- we have 1 unused slot here --
CUSTOM0 = 8,
CUSTOM1 = 9,
CUSTOM2 = 10,
CUSTOM3 = 11,
CUSTOM4 = 12,
CUSTOM5 = 13,
CUSTOM6 = 14,
CUSTOM7 = 15,
// Aliases for vertex morphing.
MORPH_POSITION_0 = CUSTOM0,
MORPH_POSITION_1 = CUSTOM1,
MORPH_POSITION_2 = CUSTOM2,
MORPH_POSITION_3 = CUSTOM3,
MORPH_TANGENTS_0 = CUSTOM4,
MORPH_TANGENTS_1 = CUSTOM5,
MORPH_TANGENTS_2 = CUSTOM6,
MORPH_TANGENTS_3 = CUSTOM7,
// this is limited by driver::MAX_VERTEX_ATTRIBUTE_COUNT
};
static constexpr size_t MAX_MORPH_TARGETS = 4;
static constexpr size_t MAX_CUSTOM_ATTRIBUTES = 8;
/**
* Material domains
*/
enum class MaterialDomain : uint8_t {
SURFACE = 0, //!< shaders applied to renderables
POST_PROCESS = 1, //!< shaders applied to rendered buffers
};
/**
* Specular occlusion
*/
enum class SpecularAmbientOcclusion : uint8_t {
NONE = 0, //!< no specular occlusion
SIMPLE = 1, //!< simple specular occlusion
BENT_NORMALS = 2, //!< more accurate specular occlusion, requires bent normals
};
/**
* Refraction
*/
enum class RefractionMode : uint8_t {
NONE = 0, //!< no refraction
CUBEMAP = 1, //!< refracted rays go to the ibl cubemap
SCREEN_SPACE = 2, //!< refracted rays go to screen space
};
/**
* Refraction type
*/
enum class RefractionType : uint8_t {
SOLID = 0, //!< refraction through solid objects (e.g. a sphere)
THIN = 1, //!< refraction through thin objects (e.g. window)
};
// can't really use std::underlying_type<AttributeIndex>::type because the driver takes a uint32_t
using AttributeBitset = utils::bitset32;
static constexpr size_t MATERIAL_PROPERTIES_COUNT = 26;
enum class Property : uint8_t {
BASE_COLOR, //!< float4, all shading models
ROUGHNESS, //!< float, lit shading models only
METALLIC, //!< float, all shading models, except unlit and cloth
REFLECTANCE, //!< float, all shading models, except unlit and cloth
AMBIENT_OCCLUSION, //!< float, lit shading models only, except subsurface and cloth
CLEAR_COAT, //!< float, lit shading models only, except subsurface and cloth
CLEAR_COAT_ROUGHNESS, //!< float, lit shading models only, except subsurface and cloth
CLEAR_COAT_NORMAL, //!< float, lit shading models only, except subsurface and cloth
ANISOTROPY, //!< float, lit shading models only, except subsurface and cloth
ANISOTROPY_DIRECTION, //!< float3, lit shading models only, except subsurface and cloth
THICKNESS, //!< float, subsurface shading model only
SUBSURFACE_POWER, //!< float, subsurface shading model only
SUBSURFACE_COLOR, //!< float3, subsurface and cloth shading models only
SHEEN_COLOR, //!< float3, lit shading models only, except subsurface
SHEEN_ROUGHNESS, //!< float3, lit shading models only, except subsurface and cloth
SPECULAR_COLOR, //!< float3, specular-glossiness shading model only
GLOSSINESS, //!< float, specular-glossiness shading model only
EMISSIVE, //!< float4, all shading models
NORMAL, //!< float3, all shading models only, except unlit
POST_LIGHTING_COLOR, //!< float4, all shading models
CLIP_SPACE_TRANSFORM, //!< mat4, vertex shader only
ABSORPTION, //!< float3, how much light is absorbed by the material
TRANSMISSION, //!< float, how much light is refracted through the material
IOR, //!< float, material's index of refraction
MICRO_THICKNESS, //!< float, thickness of the thin layer
BENT_NORMAL, //!< float3, all shading models only, except unlit
// when adding new Properties, make sure to update MATERIAL_PROPERTIES_COUNT
};
} // namespace filament
#endif

223
ios/include/filament/MaterialInstance.h Normal file
View File

@@ -0,0 +1,223 @@
/*
* 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.
*/
#ifndef TNT_FILAMENT_MATERIALINSTANCE_H
#define TNT_FILAMENT_MATERIALINSTANCE_H
#include <filament/FilamentAPI.h>
#include <filament/Color.h>
#include <backend/DriverEnums.h>
#include <utils/compiler.h>
#include <math/mathfwd.h>
namespace filament {
class Material;
class Texture;
class TextureSampler;
class UniformBuffer;
class UniformInterfaceBlock;
class UTILS_PUBLIC MaterialInstance : public FilamentAPI {
public:
using CullingMode = filament::backend::CullingMode;
template<typename T>
using is_supported_parameter_t = typename std::enable_if<
std::is_same<float, T>::value ||
std::is_same<int32_t, T>::value ||
std::is_same<uint32_t, T>::value ||
std::is_same<math::int2, T>::value ||
std::is_same<math::int3, T>::value ||
std::is_same<math::int4, T>::value ||
std::is_same<math::uint2, T>::value ||
std::is_same<math::uint3, T>::value ||
std::is_same<math::uint4, T>::value ||
std::is_same<math::float2, T>::value ||
std::is_same<math::float3, T>::value ||
std::is_same<math::float4, T>::value ||
std::is_same<math::mat4f, T>::value ||
// these types are slower as they need a layout conversion
std::is_same<bool, T>::value ||
std::is_same<math::bool2, T>::value ||
std::is_same<math::bool3, T>::value ||
std::is_same<math::bool4, T>::value ||
std::is_same<math::mat3f, T>::value
>::type;
/**
* Creates a new MaterialInstance using another MaterialInstance as a template for initialization.
* The new MaterialInstance is an instance of the same Material of the template instance and
* must be destroyed just like any other MaterialInstance.
*
* @param other A MaterialInstance to use as a template for initializing a new instance
* @param name A name for the new MaterialInstance or nullptr to use the template's name
* @return A new MaterialInstance
*/
static MaterialInstance* duplicate(MaterialInstance const* other, const char* name = nullptr) noexcept;
/**
* @return the Material associated with this instance
*/
Material const* getMaterial() const noexcept;
/**
* @return the name associated with this instance
*/
const char* getName() const noexcept;
/**
* Set a uniform by name
*
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param value Value of the parameter to set.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
template<typename T, typename = is_supported_parameter_t<T>>
void setParameter(const char* name, T const& value) noexcept;
/**
* Set a uniform array by name
*
* @param name Name of the parameter array as defined by Material. Cannot be nullptr.
* @param values Array of values to set to the named parameter array.
* @param count Size of the array to set.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
template<typename T, typename = is_supported_parameter_t<T>>
void setParameter(const char* name, const T* values, size_t count) noexcept;
/**
* Set a texture as the named parameter
*
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param texture Non nullptr Texture object pointer.
* @param sampler Sampler parameters.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
void setParameter(const char* name,
Texture const* texture, TextureSampler const& sampler) noexcept;
/**
* Set an RGB color as the named parameter.
* A conversion might occur depending on the specified type
*
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param type Whether the color value is encoded as Linear or sRGB.
* @param color Array of read, green, blue channels values.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
void setParameter(const char* name, RgbType type, math::float3 color) noexcept;
/**
* Set an RGBA color as the named parameter.
* A conversion might occur depending on the specified type
*
* @param name Name of the parameter as defined by Material. Cannot be nullptr.
* @param type Whether the color value is encoded as Linear or sRGB/A.
* @param color Array of read, green, blue and alpha channels values.
* @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
*/
void setParameter(const char* name, RgbaType type, math::float4 color) noexcept;
/**
* Set up a custom scissor rectangle; by default this encompasses the View.
*
* @param left left coordinate of the scissor box
* @param bottom bottom coordinate of the scissor box
* @param width width of the scissor box
* @param height height of the scissor box
*/
void setScissor(uint32_t left, uint32_t bottom, uint32_t width, uint32_t height) noexcept;
/**
* Returns the scissor rectangle to its default setting, which encompasses the View.
*/
void unsetScissor() noexcept;
/**
* Sets a polygon offset that will be applied to all renderables drawn with this material
* instance.
*
* The value of the offset is scale * dz + r * constant, where dz is the change in depth
* relative to the screen area of the triangle, and r is the smallest value that is guaranteed
* to produce a resolvable offset for a given implementation. This offset is added before the
* depth test.
*
* @warning using a polygon offset other than zero has a significant negative performance
* impact, as most implementations have to disable early depth culling. DO NOT USE unless
* absolutely necessary.
*
* @param scale scale factor used to create a variable depth offset for each triangle
* @param constant scale factor used to create a constant depth offset for each triangle
*/
void setPolygonOffset(float scale, float constant) noexcept;
/**
* Overrides the minimum alpha value a fragment must have to not be discarded when the blend
* mode is MASKED. Defaults to 0.4 if it has not been set in the parent Material. The specified
* value should be between 0 and 1 and will be clamped if necessary.
*/
void setMaskThreshold(float threshold) noexcept;
/**
* Sets the screen space variance of the filter kernel used when applying specular
* anti-aliasing. The default value is set to 0.15. The specified value should be between
* 0 and 1 and will be clamped if necessary.
*/
void setSpecularAntiAliasingVariance(float variance) noexcept;
/**
* Sets the clamping threshold used to suppress estimation errors when applying specular
* anti-aliasing. The default value is set to 0.2. The specified value should be between 0
* and 1 and will be clamped if necessary.
*/
void setSpecularAntiAliasingThreshold(float threshold) noexcept;
/**
* Enables or disables double-sided lighting if the parent Material has double-sided capability,
* otherwise prints a warning. If double-sided lighting is enabled, backface culling is
* automatically disabled.
*/
void setDoubleSided(bool doubleSided) noexcept;
/**
* Overrides the default triangle culling state that was set on the material.
*/
void setCullingMode(CullingMode culling) noexcept;
/**
* Overrides the default color-buffer write state that was set on the material.
*/
void setColorWrite(bool enable) noexcept;
/**
* Overrides the default depth-buffer write state that was set on the material.
*/
void setDepthWrite(bool enable) noexcept;
/**
* Overrides the default depth testing state that was set on the material.
*/
void setDepthCulling(bool enable) noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_MATERIALINSTANCE_H

175
ios/include/filament/RenderTarget.h Normal file
View File

@@ -0,0 +1,175 @@
/*
* Copyright (C) 2019 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_RENDERTARGET_H
#define TNT_FILAMENT_RENDERTARGET_H
#include <filament/FilamentAPI.h>
#include <backend/DriverEnums.h>
#include <backend/TargetBufferInfo.h>
#include <stddef.h>
namespace filament {
class FRenderTarget;
class Engine;
class Texture;
/**
* An offscreen render target that can be associated with a View and contains
* weak references to a set of attached Texture objects.
*
* Clients are responsible for the lifetime of all associated Texture attachments.
*
* @see View
*/
class UTILS_PUBLIC RenderTarget : public FilamentAPI {
struct BuilderDetails;
public:
using CubemapFace = backend::TextureCubemapFace;
/** Minimum number of color attachment supported */
static constexpr uint8_t MIN_SUPPORTED_COLOR_ATTACHMENTS_COUNT =
backend::MRT::MIN_SUPPORTED_RENDER_TARGET_COUNT;
/** Maximum number of color attachment supported */
static constexpr uint8_t MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT =
backend::MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT;
/**
* Attachment identifiers
*/
enum class AttachmentPoint : uint8_t {
COLOR0 = 0, //!< identifies the 1st color attachment
COLOR1 = 1, //!< identifies the 2nd color attachment
COLOR2 = 2, //!< identifies the 3rd color attachment
COLOR3 = 3, //!< identifies the 4th color attachment
COLOR4 = 4, //!< identifies the 5th color attachment
COLOR5 = 5, //!< identifies the 6th color attachment
COLOR6 = 6, //!< identifies the 7th color attachment
COLOR7 = 7, //!< identifies the 8th color attachment
DEPTH = MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT, //!< identifies the depth attachment
COLOR = COLOR0, //!< identifies the 1st color attachment
};
//! Use Builder to construct a RenderTarget object instance
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Sets a texture to a given attachment point.
*
* All RenderTargets must have a non-null COLOR attachment.
*
* @param attachment The attachment point of the texture.
* @param texture The associated texture object.
* @return A reference to this Builder for chaining calls.
*/
Builder& texture(AttachmentPoint attachment, Texture* texture) noexcept;
/**
* Sets the mipmap level for a given attachment point.
*
* @param attachment The attachment point of the texture.
* @param level The associated mipmap level, 0 by default.
* @return A reference to this Builder for chaining calls.
*/
Builder& mipLevel(AttachmentPoint attachment, uint8_t level) noexcept;
/**
* Sets the cubemap face for a given attachment point.
*
* @param attachment The attachment point.
* @param face The associated cubemap face.
* @return A reference to this Builder for chaining calls.
*/
Builder& face(AttachmentPoint attachment, CubemapFace face) noexcept;
/**
* Sets the layer for a given attachment point (for 3D textures).
*
* @param attachment The attachment point.
* @param layer The associated cubemap layer.
* @return A reference to this Builder for chaining calls.
*/
Builder& layer(AttachmentPoint attachment, uint32_t layer) noexcept;
/**
* Creates the RenderTarget object and returns a pointer to it.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*/
RenderTarget* build(Engine& engine);
private:
friend class FRenderTarget;
};
/**
* Gets the texture set on the given attachment point
* @param attachment Attachment point
* @return A Texture object or nullptr if no texture is set for this attachment point
*/
Texture* getTexture(AttachmentPoint attachment) const noexcept;
/**
* Returns the mipmap level set on the given attachment point
* @param attachment Attachment point
* @return the mipmap level set on the given attachment point
*/
uint8_t getMipLevel(AttachmentPoint attachment) const noexcept;
/**
* Returns the face of a cubemap set on the given attachment point
* @param attachment Attachment point
* @return A cubemap face identifier. This is only relevant if the attachment's texture is
* a cubemap.
*/
CubemapFace getFace(AttachmentPoint attachment) const noexcept;
/**
* Returns the texture-layer set on the given attachment point
* @param attachment Attachment point
* @return A texture layer. This is only relevant if the attachment's texture is a 3D texture.
*/
uint32_t getLayer(AttachmentPoint attachment) const noexcept;
/**
* Returns the number of color attachments usable by this instance of Engine. This method is
* guaranteed to return at least MIN_SUPPORTED_COLOR_ATTACHMENTS_COUNT and at most
* MAX_SUPPORTED_COLOR_ATTACHMENTS_COUNT.
* @return Number of color attachments usable in a render target.
*/
uint8_t getSupportedColorAttachmentsCount() const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_RENDERTARGET_H

585
ios/include/filament/RenderableManager.h Normal file
View File

@@ -0,0 +1,585 @@
/*
* Copyright (C) 2017 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.
*/
#ifndef TNT_FILAMENT_RENDERABLECOMPONENTMANAGER_H
#define TNT_FILAMENT_RENDERABLECOMPONENTMANAGER_H
#include <filament/Box.h>
#include <filament/FilamentAPI.h>
#include <filament/MaterialEnums.h>
#include <backend/DriverEnums.h>
#include <utils/compiler.h>
#include <utils/EntityInstance.h>
#include <math/mathfwd.h>
#include <type_traits>
namespace utils {
class Entity;
} // namespace utils
namespace filament {
class BufferObject;
class Engine;
class IndexBuffer;
class Material;
class MaterialInstance;
class Renderer;
class SkinningBuffer;
class VertexBuffer;
class FEngine;
class FRenderPrimitive;
class FRenderableManager;
/**
* Factory and manager for \em renderables, which are entities that can be drawn.
*
* Renderables are bundles of \em primitives, each of which has its own geometry and material. All
* primitives in a particular renderable share a set of rendering attributes, such as whether they
* cast shadows or use vertex skinning.
*
* Usage example:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* auto renderable = utils::EntityManager::get().create();
*
* RenderableManager::Builder(1)
* .boundingBox({{ -1, -1, -1 }, { 1, 1, 1 }})
* .material(0, matInstance)
* .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, vertBuffer, indBuffer, 0, 3)
* .receiveShadows(false)
* .build(engine, renderable);
*
* scene->addEntity(renderable);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* To modify the state of an existing renderable, clients should first use RenderableManager
* to get a temporary handle called an \em instance. The instance can then be used to get or set
* the renderable's state. Please note that instances are ephemeral; clients should store entities,
* not instances.
*
* - For details about constructing renderables, see RenderableManager::Builder.
* - To associate a 4x4 transform with an entity, see TransformManager.
* - To associate a human-readable label with an entity, see utils::NameComponentManager.
*/
class UTILS_PUBLIC RenderableManager : public FilamentAPI {
struct BuilderDetails;
public:
using Instance = utils::EntityInstance<RenderableManager>;
using PrimitiveType = backend::PrimitiveType;
/**
* Checks if the given entity already has a renderable component.
*/
bool hasComponent(utils::Entity e) const noexcept;
/**
* Gets a temporary handle that can be used to access the renderable state.
*
* @return Non-zero handle if the entity has a renderable component, 0 otherwise.
*/
Instance getInstance(utils::Entity e) const noexcept;
/**
* The transformation associated with a skinning joint.
*
* Clients can specify bones either using this quat-vec3 pair, or by using 4x4 matrices.
*/
struct Bone {
math::quatf unitQuaternion = { 1, 0, 0, 0 };
math::float3 translation = { 0, 0, 0 };
float reserved = 0;
};
/**
* Adds renderable components to entities using a builder pattern.
*/
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
enum Result { Error = -1, Success = 0 };
/**
* Creates a builder for renderable components.
*
* @param count the number of primitives that will be supplied to the builder
*
* Note that builders typically do not have a long lifetime since clients should discard
* them after calling build(). For a usage example, see RenderableManager.
*/
explicit Builder(size_t count) noexcept;
/*! \cond PRIVATE */
Builder(Builder const& rhs) = delete;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder& rhs) = delete;
Builder& operator=(Builder&& rhs) noexcept;
/*! \endcond */
/**
* Specifies the geometry data for a primitive.
*
* Filament primitives must have an associated VertexBuffer and IndexBuffer. Typically, each
* primitive is specified with a pair of daisy-chained calls: \c geometry(...) and \c
* material(...).
*
* @param index zero-based index of the primitive, must be less than the count passed to Builder constructor
* @param type specifies the topology of the primitive (e.g., \c RenderableManager::PrimitiveType::TRIANGLES)
* @param vertices specifies the vertex buffer, which in turn specifies a set of attributes
* @param indices specifies the index buffer (either u16 or u32)
* @param offset specifies where in the index buffer to start reading (expressed as a number of indices)
* @param minIndex specifies the minimum index contained in the index buffer
* @param maxIndex specifies the maximum index contained in the index buffer
* @param count number of indices to read (for triangles, this should be a multiple of 3)
*/
Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices, size_t offset, size_t minIndex, size_t maxIndex, size_t count) noexcept;
Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices, size_t offset, size_t count) noexcept; //!< \overload
Builder& geometry(size_t index, PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices) noexcept; //!< \overload
/**
* Binds a material instance to the specified primitive.
*
* If no material is specified for a given primitive, Filament will fall back to a basic default material.
*
* @param index zero-based index of the primitive, must be less than the count passed to Builder constructor
* @param materialInstance the material to bind
*/
Builder& material(size_t index, MaterialInstance const* materialInstance) noexcept;
/**
* The axis-aligned bounding box of the renderable.
*
* This is an object-space AABB used for frustum culling. For skinning and morphing, this
* should encompass all possible vertex positions. It is mandatory unless culling is
* disabled for the renderable.
*
* \see computeAABB()
*/
Builder& boundingBox(const Box& axisAlignedBoundingBox) noexcept;
/**
* Sets bits in a visibility mask. By default, this is 0x1.
*
* This feature provides a simple mechanism for hiding and showing groups of renderables
* in a Scene. See View::setVisibleLayers().
*
* For example, to set bit 1 and reset bits 0 and 2 while leaving all other bits unaffected,
* do: `builder.layerMask(7, 2)`.
*
* To change this at run time, see RenderableManager::setLayerMask.
*
* @param select the set of bits to affect
* @param values the replacement values for the affected bits
*/
Builder& layerMask(uint8_t select, uint8_t values) noexcept;
/**
* Provides coarse-grained control over draw order.
*
* In general Filament reserves the right to re-order renderables to allow for efficient
* rendering. However clients can control ordering at a coarse level using \em priority.
*
* For example, this could be used to draw a semitransparent HUD, if a client wishes to
* avoid using a separate View for the HUD. Note that priority is completely orthogonal to
* Builder::layerMask, which merely controls visibility.
*
* \see Builder::blendOrder()
*
* The priority is clamped to the range [0..7], defaults to 4; 7 is lowest priority
* (rendered last).
*/
Builder& priority(uint8_t priority) noexcept;
/**
* Controls frustum culling, true by default.
*
* \note Do not confuse frustum culling with backface culling. The latter is controlled via
* the material.
*/
Builder& culling(bool enable) noexcept;
/**
* Enables or disables a light channel. Light channel 0 is enabled by default.
*
* @param channel Light channel to enable or disable, between 0 and 7.
* @param enable Whether to enable or disable the light channel.
*/
Builder& lightChannel(unsigned int channel, bool enable = true) noexcept;
/**
* Controls if this renderable casts shadows, false by default.
*
* If the View's shadow type is set to ShadowType::VSM, castShadows should only be disabled
* if either is true:
* - receiveShadows is also disabled
* - the object is guaranteed to not cast shadows on itself or other objects (for example,
* a ground plane)
*/
Builder& castShadows(bool enable) noexcept;
/**
* Controls if this renderable receives shadows, true by default.
*/
Builder& receiveShadows(bool enable) noexcept;
/**
* Controls if this renderable uses screen-space contact shadows. This is more
* expensive but can improve the quality of shadows, especially in large scenes.
* (off by default).
*/
Builder& screenSpaceContactShadows(bool enable) noexcept;
/**
* Allows bones to be swapped out and shared using SkinningBuffer.
*
* If skinning buffer mode is enabled, clients must call setSkinningBuffer() rather than
* setBones(). This allows sharing of data between renderables.
*
* @param enabled If true, enables buffer object mode. False by default.
*/
Builder& enableSkinningBuffers(bool enabled = true) noexcept;
/**
* Enables GPU vertex skinning for up to 255 bones, 0 by default.
*
* Skinning Buffer mode must be enabled.
*
* Each vertex can be affected by up to 4 bones simultaneously. The attached
* VertexBuffer must provide data in the \c BONE_INDICES slot (uvec4) and the
* \c BONE_WEIGHTS slot (float4).
*
* See also RenderableManager::setSkinningBuffer() or SkinningBuffer::setBones(),
* which can be called on a per-frame basis to advance the animation.
*
* @param skinningBuffer nullptr to disable, otherwise the SkinningBuffer to use
* @param count 0 to disable, otherwise the number of bone transforms (up to 255)
* @param offset offset in the SkinningBuffer
*/
Builder& skinning(SkinningBuffer* skinningBuffer, size_t count, size_t offset) noexcept;
/**
* Enables GPU vertex skinning for up to 255 bones, 0 by default.
*
* Skinning Buffer mode must be disabled.
*
* Each vertex can be affected by up to 4 bones simultaneously. The attached
* VertexBuffer must provide data in the \c BONE_INDICES slot (uvec4) and the
* \c BONE_WEIGHTS slot (float4).
*
* See also RenderableManager::setBones(), which can be called on a per-frame basis
* to advance the animation.
*
* @param boneCount 0 to disable, otherwise the number of bone transforms (up to 255)
* @param transforms the initial set of transforms (one for each bone)
*/
Builder& skinning(size_t boneCount, math::mat4f const* transforms) noexcept;
Builder& skinning(size_t boneCount, Bone const* bones) noexcept; //!< \overload
Builder& skinning(size_t boneCount) noexcept; //!< \overload
/**
* Controls if the renderable has vertex morphing targets, false by default.
*
* This is required to enable GPU morphing for up to 4 attributes. The attached VertexBuffer
* must provide data in the appropriate VertexAttribute slots (\c MORPH_POSITION_0 etc).
*
* See also RenderableManager::setMorphWeights(), which can be called on a per-frame basis
* to advance the animation.
*/
Builder& morphing(bool enable) noexcept;
/**
* Sets an ordering index for blended primitives that all live at the same Z value.
*
* @param primitiveIndex the primitive of interest
* @param order draw order number (0 by default). Only the lowest 15 bits are used.
*/
Builder& blendOrder(size_t primitiveIndex, uint16_t order) noexcept;
/**
* Adds the Renderable component to an entity.
*
* @param engine Reference to the filament::Engine to associate this Renderable with.
* @param entity Entity to add the Renderable component to.
* @return Success if the component was created successfully, Error otherwise.
*
* If exceptions are disabled and an error occurs, this function is a no-op.
* Success can be checked by looking at the return value.
*
* If this component already exists on the given entity and the construction is successful,
* it is first destroyed as if destroy(utils::Entity e) was called. In case of error,
* the existing component is unmodified.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*/
Result build(Engine& engine, utils::Entity entity);
private:
friend class FEngine;
friend class FRenderPrimitive;
friend class FRenderableManager;
struct Entry {
VertexBuffer* vertices = nullptr;
IndexBuffer* indices = nullptr;
size_t offset = 0;
size_t minIndex = 0;
size_t maxIndex = 0;
size_t count = 0;
MaterialInstance const* materialInstance = nullptr;
PrimitiveType type = PrimitiveType::TRIANGLES;
uint16_t blendOrder = 0;
};
};
/**
* Destroys the renderable component in the given entity.
*/
void destroy(utils::Entity e) noexcept;
/**
* Changes the bounding box used for frustum culling.
*
* \see Builder::boundingBox()
* \see RenderableManager::getAxisAlignedBoundingBox()
*/
void setAxisAlignedBoundingBox(Instance instance, const Box& aabb) noexcept;
/**
* Changes the visibility bits.
*
* \see Builder::layerMask()
* \see View::setVisibleLayers().
* \see RenderableManager::getLayerMask()
*/
void setLayerMask(Instance instance, uint8_t select, uint8_t values) noexcept;
/**
* Changes the coarse-level draw ordering.
*
* \see Builder::priority().
*/
void setPriority(Instance instance, uint8_t priority) noexcept;
/**
* Changes whether or not frustum culling is on.
*
* \see Builder::culling()
*/
void setCulling(Instance instance, bool enable) noexcept;
/**
* Enables or disables a light channel.
* Light channel 0 is enabled by default.
*
* \see Builder::lightChannel()
*/
void setLightChannel(Instance instance, unsigned int channel, bool enable) noexcept;
/**
* Returns whether a light channel is enabled on a specified renderable.
* @param instance Instance of the component obtained from getInstance().
* @param channel Light channel to query
* @return true if the light channel is enabled, false otherwise
*/
bool getLightChannel(Instance instance, unsigned int channel) const noexcept;
/**
* Changes whether or not the renderable casts shadows.
*
* \see Builder::castShadows()
*/
void setCastShadows(Instance instance, bool enable) noexcept;
/**
* Changes whether or not the renderable can receive shadows.
*
* \see Builder::receiveShadows()
*/
void setReceiveShadows(Instance instance, bool enable) noexcept;
/**
* Changes whether or not the renderable can use screen-space contact shadows.
*
* \see Builder::screenSpaceContactShadows()
*/
void setScreenSpaceContactShadows(Instance instance, bool enable) noexcept;
/**
* Checks if the renderable can cast shadows.
*
* \see Builder::castShadows().
*/
bool isShadowCaster(Instance instance) const noexcept;
/**
* Checks if the renderable can receive shadows.
*
* \see Builder::receiveShadows().
*/
bool isShadowReceiver(Instance instance) const noexcept;
/**
* Updates the bone transforms in the range [offset, offset + boneCount).
* The bones must be pre-allocated using Builder::skinning().
*/
void setBones(Instance instance, Bone const* transforms, size_t boneCount = 1, size_t offset = 0) noexcept;
void setBones(Instance instance, math::mat4f const* transforms, size_t boneCount = 1, size_t offset = 0) noexcept; //!< \overload
/**
* Associates a SkinningBuffer to a renderable instance
*/
void setSkinningBuffer(Instance instance, SkinningBuffer* skinningBuffer,
size_t count, size_t offset) noexcept;
/**
* Updates the vertex morphing weights on a renderable, all zeroes by default.
*
* This is specified using a 4-tuple, one float per morph target. If the renderable has fewer
* than 4 morph targets, then clients should fill the unused components with zeroes.
*
* The renderable must be built with morphing enabled, see Builder::morphing().
*/
void setMorphWeights(Instance instance, math::float4 const& weights) noexcept;
/**
* Gets the bounding box used for frustum culling.
*
* \see Builder::boundingBox()
* \see RenderableManager::setAxisAlignedBoundingBox()
*/
const Box& getAxisAlignedBoundingBox(Instance instance) const noexcept;
/**
* Get the visibility bits.
*
* \see Builder::layerMask()
* \see View::setVisibleLayers().
* \see RenderableManager::getLayerMask()
*/
uint8_t getLayerMask(Instance instance) const noexcept;
/**
* Gets the immutable number of primitives in the given renderable.
*/
size_t getPrimitiveCount(Instance instance) const noexcept;
/**
* Changes the material instance binding for the given primitive.
*
* \see Builder::material()
*/
void setMaterialInstanceAt(Instance instance,
size_t primitiveIndex, MaterialInstance const* materialInstance) noexcept;
/**
* Retrieves the material instance that is bound to the given primitive.
*/
MaterialInstance* getMaterialInstanceAt(Instance instance, size_t primitiveIndex) const noexcept;
/**
* Changes the geometry for the given primitive.
*
* \see Builder::geometry()
*/
void setGeometryAt(Instance instance, size_t primitiveIndex,
PrimitiveType type, VertexBuffer* vertices, IndexBuffer* indices,
size_t offset, size_t count) noexcept;
/**
* Changes the active range of indices or topology for the given primitive.
*
* \see Builder::geometry()
*/
void setGeometryAt(Instance instance, size_t primitiveIndex,
PrimitiveType type, size_t offset, size_t count) noexcept;
/**
* Changes the ordering index for blended primitives that all live at the same Z value.
*
* \see Builder::blendOrder()
*
* @param instance the renderable of interest
* @param primitiveIndex the primitive of interest
* @param order draw order number (0 by default). Only the lowest 15 bits are used.
*/
void setBlendOrderAt(Instance instance, size_t primitiveIndex, uint16_t order) noexcept;
/**
* Retrieves the set of enabled attribute slots in the given primitive's VertexBuffer.
*/
AttributeBitset getEnabledAttributesAt(Instance instance, size_t primitiveIndex) const noexcept;
/*! \cond PRIVATE */
template<typename T>
struct is_supported_vector_type {
using type = typename std::enable_if<
std::is_same<math::float4, T>::value ||
std::is_same<math::half4, T>::value ||
std::is_same<math::float3, T>::value ||
std::is_same<math::half3, T>::value
>::type;
};
template<typename T>
struct is_supported_index_type {
using type = typename std::enable_if<
std::is_same<uint16_t, T>::value ||
std::is_same<uint32_t, T>::value
>::type;
};
/*! \endcond */
/**
* Utility method that computes the axis-aligned bounding box from a set of vertices.
*
* - The index type must be \c uint16_t or \c uint32_t.
* - The vertex type must be \c float4, \c half4, \c float3, or \c half3.
* - For 4-component vertices, the w component is ignored (implicitly replaced with 1.0).
*/
template<typename VECTOR, typename INDEX,
typename = typename is_supported_vector_type<VECTOR>::type,
typename = typename is_supported_index_type<INDEX>::type>
static Box computeAABB(VECTOR const* vertices, INDEX const* indices, size_t count,
size_t stride = sizeof(VECTOR)) noexcept;
};
template<typename VECTOR, typename INDEX, typename, typename>
Box RenderableManager::computeAABB(VECTOR const* vertices, INDEX const* indices, size_t count,
size_t stride) noexcept {
math::float3 bmin(std::numeric_limits<float>::max());
math::float3 bmax(std::numeric_limits<float>::lowest());
for (size_t i = 0; i < count; ++i) {
VECTOR const* p = reinterpret_cast<VECTOR const*>(
(char const*)vertices + indices[i] * stride);
const math::float3 v(p->x, p->y, p->z);
bmin = min(bmin, v);
bmax = max(bmax, v);
}
return Box().set(bmin, bmax);
}
} // namespace filament
#endif // TNT_FILAMENT_RENDERABLECOMPONENTMANAGER_H

540
ios/include/filament/Renderer.h Normal file
View File

@@ -0,0 +1,540 @@
/*
* 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_RENDERER_H
#define TNT_FILAMENT_RENDERER_H
#include <filament/FilamentAPI.h>
#include <utils/compiler.h>
#include <backend/PresentCallable.h>
#include <backend/DriverEnums.h>
#include <math/vec4.h>
#include <stdint.h>
namespace filament {
class Engine;
class RenderTarget;
class SwapChain;
class View;
class Viewport;
namespace backend {
class PixelBufferDescriptor;
} // namespace backend
/**
* A Renderer instance represents an operating system's window.
*
* Typically, applications create a Renderer per window. The Renderer generates drawing commands
* for the render thread and manages frame latency.
*
* A Renderer generates drawing commands from a View, itself containing a Scene description.
*
* Creation and Destruction
* ========================
*
* A Renderer is created using Engine.createRenderer() and destroyed using
* Engine.destroy(const Renderer*).
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* #include <filament/Renderer.h>
* #include <filament/Engine.h>
* using namespace filament;
*
* Engine* engine = Engine::create();
*
* Renderer* renderer = engine->createRenderer();
* engine->destroy(&renderer);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* @see Engine, View
*/
class UTILS_PUBLIC Renderer : public FilamentAPI {
public:
/**
* Use DisplayInfo to set important Display properties. This is used to achieve correct
* frame pacing and dynamic resolution scaling.
*/
struct DisplayInfo {
// refresh-rate of the display in Hz. set to 0 for offscreen or turn off frame-pacing.
float refreshRate = 60.0f;
// how far in advance a buffer must be queued for presentation at a given time in ns
uint64_t presentationDeadlineNanos = 0;
// offset by which vsyncSteadyClockTimeNano provided in beginFrame() is offset in ns
uint64_t vsyncOffsetNanos = 0;
};
/**
* Use FrameRateOptions to set the desired frame rate and control how quickly the system
* reacts to GPU load changes.
*
* interval: desired frame interval in multiple of the refresh period, set in DisplayInfo
* (as 1 / DisplayInfo::refreshRate)
*
* The parameters below are relevant when some Views are using dynamic resolution scaling:
*
* headRoomRatio: additional headroom for the GPU as a ratio of the targetFrameTime.
* Useful for taking into account constant costs like post-processing or
* GPU drivers on different platforms.
* history: History size. higher values, tend to filter more (clamped to 30)
* scaleRate: rate at which the gpu load is adjusted to reach the target frame rate
* This value can be computed as 1 / N, where N is the number of frames
* needed to reach 64% of the target scale factor.
* Higher values make the dynamic resolution react faster.
*
* @see View::DynamicResolutionOptions
* @see Renderer::DisplayInfo
*
*/
struct FrameRateOptions {
float headRoomRatio = 0.0f; //!< additional headroom for the GPU
float scaleRate = 0.125f; //!< rate at which the system reacts to load changes
uint8_t history = 3; //!< history size
uint8_t interval = 1; //!< desired frame interval in unit of 1.0 / DisplayInfo::refreshRate
};
/**
* ClearOptions are used at the beginning of a frame to clear or retain the SwapChain content.
*/
struct ClearOptions {
/** Color to use to clear the SwapChain */
math::float4 clearColor = {};
/**
* Whether the SwapChain should be cleared using the clearColor. Use this if translucent
* View will be drawn, for instance.
*/
bool clear = false;
/**
* Whether the SwapChain content should be discarded. clear implies discard. Set this
* to false (along with clear to false as well) if the SwapChain already has content that
* needs to be preserved
*/
bool discard = true;
};
/**
* Information about the display this Renderer is associated to. This information is needed
* to accurately compute dynamic-resolution scaling and for frame-pacing.
*/
void setDisplayInfo(const DisplayInfo& info) noexcept;
/**
* Set options controlling the desired frame-rate.
*/
void setFrameRateOptions(FrameRateOptions const& options) noexcept;
/**
* Set ClearOptions which are used at the beginning of a frame to clear or retain the
* SwapChain content.
*/
void setClearOptions(const ClearOptions& options);
/**
* Get the Engine that created this Renderer.
*
* @return A pointer to the Engine instance this Renderer is associated to.
*/
Engine* getEngine() noexcept;
/**
* Get the Engine that created this Renderer.
*
* @return A constant pointer to the Engine instance this Renderer is associated to.
*/
inline Engine const* getEngine() const noexcept {
return const_cast<Renderer *>(this)->getEngine();
}
/**
* Flags used to configure the behavior of copyFrame().
*
* @see
* copyFrame()
*/
using CopyFrameFlag = uint32_t;
/**
* Indicates that the dstSwapChain passed into copyFrame() should be
* committed after the frame has been copied.
*
* @see
* copyFrame()
*/
static constexpr CopyFrameFlag COMMIT = 0x1;
/**
* Indicates that the presentation time should be set on the dstSwapChain
* passed into copyFrame to the monotonic clock time when the frame is
* copied.
*
* @see
* copyFrame()
*/
static constexpr CopyFrameFlag SET_PRESENTATION_TIME = 0x2;
/**
* Indicates that the dstSwapChain passed into copyFrame() should be
* cleared to black before the frame is copied into the specified viewport.
*
* @see
* copyFrame()
*/
static constexpr CopyFrameFlag CLEAR = 0x4;
/**
* Set-up a frame for this Renderer.
*
* beginFrame() manages frame pacing, and returns whether or not a frame should be drawn. The
* goal of this is to skip frames when the GPU falls behind in order to keep the frame
* latency low.
*
* If a given frame takes too much time in the GPU, the CPU will get ahead of the GPU. The
* display will draw the same frame twice producing a stutter. At this point, the CPU is
* ahead of the GPU and depending on how many frames are buffered, latency increases.
*
* beginFrame() attempts to detect this situation and returns false in that case, indicating
* to the caller to skip the current frame.
*
* When beginFrame() returns true, it is mandatory to render the frame and call endFrame().
* However, when beginFrame() returns false, the caller has the choice to either skip the
* frame and not call endFrame(), or proceed as though true was returned.
*
* @param vsyncSteadyClockTimeNano The time in nanosecond of when the current frame started,
* or 0 if unknown. This value should be the timestamp of
* the last h/w vsync. It is expressed in the
* std::chrono::steady_clock time base.
* @param swapChain A pointer to the SwapChain instance to use.
*
* @return
* *false* the current frame should be skipped,
* *true* the current frame must be drawn and endFrame() must be called.
*
* @remark
* When skipping a frame, the whole frame is canceled, and endFrame() must not be called.
*
* @note
* All calls to render() must happen *after* beginFrame().
*
* @see
* endFrame()
*/
bool beginFrame(SwapChain* swapChain,
uint64_t vsyncSteadyClockTimeNano = 0u);
/**
* Render a View into this renderer's window.
*
* This is filament main rendering method, most of the CPU-side heavy lifting is performed
* here. render() main function is to generate render commands which are asynchronously
* executed by the Engine's render thread.
*
* render() generates commands for each of the following stages:
*
* 1. Shadow map pass, if needed (currently only a single shadow map is supported).
* 2. Depth pre-pass.
* 3. Color pass.
* 4. Post-processing pass.
*
* A typical render loop looks like this:
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* #include <filament/Renderer.h>
* #include <filament/View.h>
* using namespace filament;
*
* void renderLoop(Renderer* renderer, SwapChain* swapChain) {
* do {
* // typically we wait for VSYNC and user input events
* if (renderer->beginFrame(swapChain)) {
* renderer->render(mView);
* renderer->endFrame();
* }
* } while (!quit());
* }
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
*
* @param view A pointer to the view to render.
*
* @attention
* render() must be called *after* beginFrame() and *before* endFrame().
*
* @note
* render() must be called from the Engine's main thread (or external synchronization
* must be provided). In particular, calls to render() on different Renderer instances
* **must** be synchronized.
*
* @remark
* render() perform potentially heavy computations and cannot be multi-threaded. However,
* internally, render() is highly multi-threaded to both improve performance in mitigate
* the call's latency.
*
* @remark
* render() is typically called once per frame (but not necessarily).
*
* @see
* beginFrame(), endFrame(), View
*
*/
void render(View const* view);
/**
* Copy the currently rendered view to the indicated swap chain, using the
* indicated source and destination rectangle.
*
* @param dstSwapChain The swap chain into which the frame should be copied.
* @param dstViewport The destination rectangle in which to draw the view.
* @param srcViewport The source rectangle to be copied.
* @param flags One or more CopyFrameFlag behavior configuration flags.
*
* @remark
* copyFrame() should be called after a frame is rendered using render()
* but before endFrame() is called.
*/
void copyFrame(SwapChain* dstSwapChain, Viewport const& dstViewport,
Viewport const& srcViewport, uint32_t flags = 0);
/**
* Reads back the content of the SwapChain associated with this Renderer.
*
* @param xoffset Left offset of the sub-region to read back.
* @param yoffset Bottom offset of the sub-region to read back.
* @param width Width of the sub-region to read back.
* @param height Height of the sub-region to read back.
* @param buffer Client-side buffer where the read-back will be written.
*
* The following formats are always supported:
* - PixelBufferDescriptor::PixelDataFormat::RGBA
* - PixelBufferDescriptor::PixelDataFormat::RGBA_INTEGER
*
* The following types are always supported:
* - PixelBufferDescriptor::PixelDataType::UBYTE
* - PixelBufferDescriptor::PixelDataType::UINT
* - PixelBufferDescriptor::PixelDataType::INT
* - PixelBufferDescriptor::PixelDataType::FLOAT
*
* Other combinations of format/type may be supported. If a combination is
* not supported, this operation may fail silently. Use a DEBUG build
* to get some logs about the failure.
*
*
* Framebuffer as seen on User buffer (PixelBufferDescriptor&)
* screen
*
* +--------------------+
* | | .stride .alignment
* | | ----------------------->-->
* | | O----------------------+--+ low addresses
* | | | | | |
* | w | | | .top | |
* | <---------> | | V | |
* | +---------+ | | +---------+ | |
* | | ^ | | ======> | | | | |
* | x | h| | | |.left| | | |
* +------>| v | | +---->| | | |
* | +.........+ | | +.........+ | |
* | ^ | | | |
* | y | | +----------------------+--+ high addresses
* O------------+-------+
*
*
* Typically readPixels() will be called after render() and before endFrame().
*
* After issuing this method, the callback associated with `buffer` will be invoked on the
* main thread, indicating that the read-back has completed. Typically, this will happen
* after multiple calls to beginFrame(), render(), endFrame().
*
* It is also possible to use a Fence to wait for the read-back.
*
* @remark
* readPixels() is intended for debugging and testing. It will impact performance significantly.
*
*/
void readPixels(uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height,
backend::PixelBufferDescriptor&& buffer);
/**
* Finishes the current frame and schedules it for display.
*
* endFrame() schedules the current frame to be displayed on the Renderer's window.
*
* @note
* All calls to render() must happen *before* endFrame(). endFrame() must be called if
* beginFrame() returned true, otherwise, endFrame() must not be called unless the caller
* ignored beginFrame()'s return value.
*
* @see
* beginFrame()
*/
void endFrame();
/**
* Reads back the content of the provided RenderTarget.
*
* @param renderTarget RenderTarget to read back from.
* @param xoffset Left offset of the sub-region to read back.
* @param yoffset Bottom offset of the sub-region to read back.
* @param width Width of the sub-region to read back.
* @param height Height of the sub-region to read back.
* @param buffer Client-side buffer where the read-back will be written.
*
* The following formats are always supported:
* - PixelBufferDescriptor::PixelDataFormat::RGBA
* - PixelBufferDescriptor::PixelDataFormat::RGBA_INTEGER
*
* The following types are always supported:
* - PixelBufferDescriptor::PixelDataType::UBYTE
* - PixelBufferDescriptor::PixelDataType::UINT
* - PixelBufferDescriptor::PixelDataType::INT
* - PixelBufferDescriptor::PixelDataType::FLOAT
*
* Other combinations of format/type may be supported. If a combination is
* not supported, this operation may fail silently. Use a DEBUG build
* to get some logs about the failure.
*
*
* Framebuffer as seen on User buffer (PixelBufferDescriptor&)
* screen
*
* +--------------------+
* | | .stride .alignment
* | | ----------------------->-->
* | | O----------------------+--+ low addresses
* | | | | | |
* | w | | | .top | |
* | <---------> | | V | |
* | +---------+ | | +---------+ | |
* | | ^ | | ======> | | | | |
* | x | h| | | |.left| | | |
* +------>| v | | +---->| | | |
* | +.........+ | | +.........+ | |
* | ^ | | | |
* | y | | +----------------------+--+ high addresses
* O------------+-------+
*
*
* Typically readPixels() will be called after render() and before endFrame().
*
* After issuing this method, the callback associated with `buffer` will be invoked on the
* main thread, indicating that the read-back has completed. Typically, this will happen
* after multiple calls to beginFrame(), render(), endFrame().
*
* It is also possible to use a Fence to wait for the read-back.
*
* @remark
* readPixels() is intended for debugging and testing. It will impact performance significantly.
*
*/
void readPixels(RenderTarget* renderTarget,
uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height,
backend::PixelBufferDescriptor&& buffer);
/**
* Render a standalone View into its associated RenderTarget
*
* This call is mostly equivalent to calling render(View*) inside a
* beginFrame / endFrame block, but incurs less overhead. It can be used
* as a poor man's compute API.
*
* @param view A pointer to the view to render. This View must have a RenderTarget associated
* to it.
*
* @attention
* renderStandaloneView() must be called outside of beginFrame() / endFrame().
*
* @note
* renderStandaloneView() must be called from the Engine's main thread
* (or external synchronization must be provided). In particular, calls to
* renderStandaloneView() on different Renderer instances **must** be synchronized.
*
* @remark
* renderStandaloneView() perform potentially heavy computations and cannot be multi-threaded.
* However, internally, renderStandaloneView() is highly multi-threaded to both improve
* performance in mitigate the call's latency.
*/
void renderStandaloneView(View const* view);
/**
* Returns the time in second of the last call to beginFrame(). This value is constant for all
* views rendered during a frame. The epoch is set with resetUserTime().
*
* In materials, this value can be queried using `vec4 getUserTime()`. The value returned
* is a highp vec4 encoded as follows:
*
* time.x = (float)Renderer.getUserTime();
* time.y = Renderer.getUserTime() - time.x;
*
* It follows that the following invariants are true:
*
* (double)time.x + (double)time.y == Renderer.getUserTime()
* time.x == (float)Renderer.getUserTime()
*
* This encoding allows the shader code to perform high precision (i.e. double) time
* calculations when needed despite the lack of double precision in the shader, for e.g.:
*
* To compute (double)time * vertex in the material, use the following construct:
*
* vec3 result = time.x * vertex + time.y * vertex;
*
*
* Most of the time, high precision computations are not required, but be aware that the
* precision of time.x rapidly diminishes as time passes:
*
* time | precision
* --------+----------
* 16.7s | us
* 4h39 | ms
* 77h | 1/60s
*
*
* In other words, it only possible to get microsecond accuracy for about 16s or millisecond
* accuracy for just under 5h.
*
* This problem can be mitigated by calling resetUserTime(), or using high precision time as
* described above.
*
* @return The time is seconds since resetUserTime() was last called.
*
* @see
* resetUserTime()
*/
double getUserTime() const;
/**
* Sets the user time epoch to now, i.e. resets the user time to zero.
*
* Use this method used to keep the precision of time high in materials, in practice it should
* be called at least when the application is paused, e.g. Activity.onPause() in Android.
*
* @see
* getUserTime()
*/
void resetUserTime();
};
} // namespace filament
#endif // TNT_FILAMENT_RENDERER_H

163
ios/include/filament/Scene.h Normal file
View File

@@ -0,0 +1,163 @@
/*
* 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_SCENE_H
#define TNT_FILAMENT_SCENE_H
#include <filament/FilamentAPI.h>
#include <utils/compiler.h>
namespace utils {
class Entity;
} // namespace utils
namespace filament {
class IndirectLight;
class Skybox;
/**
* A Scene is a flat container of Renderable and Light instances.
*
* A Scene doesn't provide a hierarchy of Renderable objects, i.e.: it's not a scene-graph.
* However, it manages the list of objects to render and the list of lights. Renderable
* and Light objects can be added or removed from a Scene at any time.
*
* A Renderable *must* be added to a Scene in order to be rendered, and the Scene must be
* provided to a View.
*
*
* Creation and Destruction
* ========================
*
* A Scene is created using Engine.createScene() and destroyed using
* Engine.destroy(const Scene*).
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* #include <filament/Scene.h>
* #include <filament/Engine.h>
* using namespace filament;
*
* Engine* engine = Engine::create();
*
* Scene* scene = engine->createScene();
* engine->destroy(&scene);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* @see View, Renderable, Light
*/
class UTILS_PUBLIC Scene : public FilamentAPI {
public:
/**
* Sets the Skybox.
*
* The Skybox is drawn last and covers all pixels not touched by geometry.
*
* @param skybox The Skybox to use to fill untouched pixels, or nullptr to unset the Skybox.
*/
void setSkybox(Skybox* skybox) noexcept;
/**
* Returns the Skybox associated with the Scene.
*
* @return The associated Skybox, or nullptr if there is none.
*/
Skybox* getSkybox() noexcept;
/**
* Returns an immutable Skybox associated with the Scene.
*
* @return The associated Skybox, or nullptr if there is none.
*/
Skybox const* getSkybox() const noexcept;
/**
* Set the IndirectLight to use when rendering the Scene.
*
* Currently, a Scene may only have a single IndirectLight. This call replaces the current
* IndirectLight.
*
* @param ibl The IndirectLight to use when rendering the Scene or nullptr to unset.
*/
void setIndirectLight(IndirectLight const* ibl) noexcept;
/**
* Adds an Entity to the Scene.
*
* @param entity The entity is ignored if it doesn't have a Renderable or Light component.
*
* \attention
* A given Entity object can only be added once to a Scene.
*
*/
void addEntity(utils::Entity entity);
/**
* Adds a list of entities to the Scene.
*
* @param entities Array containing entities to add to the scene.
* @param count Size of the entity array.
*/
void addEntities(const utils::Entity* entities, size_t count);
/**
* Removes the Renderable from the Scene.
*
* @param entity The Entity to remove from the Scene. If the specified
* \p entity doesn't exist, this call is ignored.
*/
void remove(utils::Entity entity);
/**
* Removes a list of entities to the Scene.
*
* This is equivalent to calling remove in a loop.
* If any of the specified entities do not exist in the scene, they are skipped.
*
* @param entities Array containing entities to remove from the scene.
* @param count Size of the entity array.
*/
void removeEntities(const utils::Entity* entities, size_t count);
/**
* Returns the number of Renderable objects in the Scene.
*
* @return number of Renderable objects in the Scene.
*/
size_t getRenderableCount() const noexcept;
/**
* Returns the total number of Light objects in the Scene.
*
* @return The total number of Light objects in the Scene.
*/
size_t getLightCount() const noexcept;
/**
* Returns true if the given entity is in the Scene.
*
* @return Whether the given entity is in the Scene.
*/
bool hasEntity(utils::Entity entity) const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_SCENE_H

119
ios/include/filament/SkinningBuffer.h Normal file
View File

@@ -0,0 +1,119 @@
/*
* Copyright (C) 2021 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.
*/
#ifndef TNT_FILAMENT_SKINNINGBUFFER_H
#define TNT_FILAMENT_SKINNINGBUFFER_H
#include <filament/FilamentAPI.h>
#include <filament/RenderableManager.h>
#include <utils/compiler.h>
#include <math/mathfwd.h>
#include <stddef.h>
namespace filament {
/**
* SkinningBuffer is used to hold skinning data (bones). It is a simple wraper around
* a structured UBO.
*/
class UTILS_PUBLIC SkinningBuffer : public FilamentAPI {
struct BuilderDetails;
public:
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Size of the skinning buffer in bones.
*
* Due to limitation in the GLSL, the SkinningBuffer must always by a multiple of
* 256, this adjustment is done automatically, but can cause
* some memory overhead. This memory overhead can be mitigated by using the same
* SkinningBuffer to store the bone information for multiple RenderPrimitives.
*
* @param boneCount Number of bones the skinning buffer can hold.
* @return A reference to this Builder for chaining calls.
*/
Builder& boneCount(uint32_t boneCount) noexcept;
/**
* The new buffer is created with identity bones
* @param initialize true to initializing the buffer, false to not.
* @return A reference to this Builder for chaining calls.
*/
Builder& initialize(bool initialize = true) noexcept;
/**
* Creates the SkinningBuffer object and returns a pointer to it.
*
* @param engine Reference to the filament::Engine to associate this SkinningBuffer with.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*
* @see SkinningBuffer::setBones
*/
SkinningBuffer* build(Engine& engine);
private:
friend class FSkinningBuffer;
};
/**
* Updates the bone transforms in the range [offset, offset + count).
* @param engine Reference to the filament::Engine to associate this SkinningBuffer with.
* @param transforms pointer to at least count Bone
* @param count number of Bone elements in transforms
* @param offset offset in elements (not bytes) in the SkinningBuffer (not in transforms)
*/
void setBones(Engine& engine, RenderableManager::Bone const* transforms,
size_t count, size_t offset = 0);
/**
* Updates the bone transforms in the range [offset, offset + count).
* @param engine Reference to the filament::Engine to associate this SkinningBuffer with.
* @param transforms pointer to at least count mat4f
* @param count number of mat4f elements in transforms
* @param offset offset in elements (not bytes) in the SkinningBuffer (not in transforms)
*/
void setBones(Engine& engine, math::mat4f const* transforms,
size_t count, size_t offset = 0);
/**
* Returns the size of this SkinningBuffer in elements.
* @return The number of bones the SkinningBuffer holds.
*/
size_t getBoneCount() const noexcept;
};
} // namespace filament
#endif //TNT_FILAMENT_SKINNINGBUFFER_H

181
ios/include/filament/Skybox.h Normal file
View File

@@ -0,0 +1,181 @@
/*
* Copyright (C) 2016 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_SKYBOX_H
#define TNT_FILAMENT_SKYBOX_H
#include <filament/FilamentAPI.h>
#include <utils/compiler.h>
#include <stdint.h>
#include <math/mathfwd.h>
namespace filament {
class FSkybox;
class Engine;
class Texture;
/**
* Skybox
*
* When added to a Scene, the Skybox fills all untouched pixels.
*
* Creation and destruction
* ========================
*
* A Skybox object is created using the Skybox::Builder and destroyed by calling
* Engine::destroy(const Skybox*).
*
* ~~~~~~~~~~~{.cpp}
* filament::Engine* engine = filament::Engine::create();
*
* filament::IndirectLight* skybox = filament::Skybox::Builder()
* .environment(cubemap)
* .build(*engine);
*
* engine->destroy(skybox);
* ~~~~~~~~~~~
*
*
* @note
* Currently only Texture based sky boxes are supported.
*
* @see Scene, IndirectLight
*/
class UTILS_PUBLIC Skybox : public FilamentAPI {
struct BuilderDetails;
public:
//! Use Builder to construct an Skybox object instance
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Set the environment map (i.e. the skybox content).
*
* The Skybox is rendered as though it were an infinitely large cube with the camera
* inside it. This means that the cubemap which is mapped onto the cube's exterior
* will appear mirrored. This follows the OpenGL conventions.
*
* The cmgen tool generates reflection maps by default which are therefore ideal to use
* as skyboxes.
*
* @param cubemap This Texture must be a cube map.
*
* @return This Builder, for chaining calls.
*
* @see Texture
*/
Builder& environment(Texture* cubemap) noexcept;
/**
* Indicates whether the sun should be rendered. The sun can only be
* rendered if there is at least one light of type SUN in the scene.
* The default value is false.
*
* @param show True if the sun should be rendered, false otherwise
*
* @return This Builder, for chaining calls.
*/
Builder& showSun(bool show) noexcept;
/**
* Skybox intensity when no IndirectLight is set on the Scene.
*
* This call is ignored when an IndirectLight is set on the Scene, and the intensity
* of the IndirectLight is used instead.
*
* @param envIntensity Scale factor applied to the skybox texel values such that
* the result is in lux, or lumen/m^2 (default = 30000)
*
* @return This Builder, for chaining calls.
*
* @see IndirectLight::Builder::intensity
*/
Builder& intensity(float envIntensity) noexcept;
/**
* Sets the skybox to a constant color. Default is opaque black.
*
* Ignored if an environment is set.
*
* @param color
*
* @return This Builder, for chaining calls.
*/
Builder& color(math::float4 color) noexcept;
/**
* Creates the Skybox object and returns a pointer to it.
*
* @param engine Reference to the filament::Engine to associate this Skybox with.
*
* @return pointer to the newly created object, or nullptr if the light couldn't be created.
*/
Skybox* build(Engine& engine);
private:
friend class FSkybox;
};
void setColor(math::float4 color) noexcept;
/**
* Sets bits in a visibility mask. By default, this is 0x1.
*
* This provides a simple mechanism for hiding or showing this Skybox in a Scene.
*
* @see View::setVisibleLayers().
*
* For example, to set bit 1 and reset bits 0 and 2 while leaving all other bits unaffected,
* call: `setLayerMask(7, 2)`.
*
* @param select the set of bits to affect
* @param values the replacement values for the affected bits
*/
void setLayerMask(uint8_t select, uint8_t values) noexcept;
/**
* @return the visibility mask bits
*/
uint8_t getLayerMask() const noexcept;
/**
* Returns the skybox's intensity in lux, or lumen/m^2.
*/
float getIntensity() const noexcept;
/**
* @return the associated texture, or null if it does not exist
*/
Texture const* getTexture() const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_SKYBOX_H

281
ios/include/filament/Stream.h Normal file
View File

@@ -0,0 +1,281 @@
/*
* Copyright (C) 2017 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.
*/
#ifndef TNT_FILAMENT_STREAM_H
#define TNT_FILAMENT_STREAM_H
#include <filament/FilamentAPI.h>
#include <backend/DriverEnums.h>
#include <backend/PixelBufferDescriptor.h>
#include <utils/compiler.h>
namespace filament {
class FStream;
class Engine;
/**
* Stream is used to attach a video stream to a Filament `Texture`.
*
* Note that the `Stream` class is fairly Android centric. It supports three different
* configurations:
*
* - TEXTURE_ID...takes an OpenGL texture ID and incurs a copy
* - ACQUIRED.....connects to an Android AHardwareBuffer
* - NATIVE.......connects to an Android SurfaceTexture
*
* Before explaining these different configurations, let's review the high-level structure of an AR
* or video application that uses Filament:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* while (true) {
*
* // Misc application work occurs here, such as:
* // - Writing the image data for a video frame into a Stream
* // - Moving the Filament Camera
*
* if (renderer->beginFrame(swapChain)) {
* renderer->render(view);
* renderer->endFrame();
* }
* }
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Let's say that the video image data at the time of a particular invocation of `beginFrame`
* becomes visible to users at time A. The 3D scene state (including the camera) at the time of
* that same invocation becomes apparent to users at time B.
*
* - If time A matches time B, we say that the stream is \em{synchronized}.
* - Filament invokes low-level graphics commands on the \em{driver thread}.
* - The thread that calls `beginFrame` is called the \em{main thread}.
*
* The TEXTURE_ID configuration achieves synchronization automatically. In this mode, Filament
* performs a copy on the main thread during `beginFrame` by blitting the external image into
* an internal round-robin queue of images. This copy has a run-time cost.
*
* For ACQUIRED streams, there is no need to perform the copy because Filament explictly acquires
* the stream, then releases it later via a callback function. This configuration is especially
* useful when the Vulkan backend is enabled.
*
* For NATIVE streams, Filament does not make any synchronization guarantee. However they are simple
* to use and do not incur a copy. These are often appropriate in video applications.
*
* Please see `sample-stream-test` and `sample-hello-camera` for usage examples.
*
* @see backend::StreamType
* @see Texture#setExternalStream
* @see Engine#destroyStream
*/
class UTILS_PUBLIC Stream : public FilamentAPI {
struct BuilderDetails;
public:
using Callback = backend::StreamCallback;
using StreamType = backend::StreamType;
/**
* Constructs a Stream object instance.
*
* By default, Stream objects are ACQUIRED and must have external images pushed to them via
* <pre>Stream::setAcquiredImage</pre>.
*
* To create a NATIVE or TEXTURE_ID stream, call one of the <pre>stream</pre> methods
* on the builder.
*/
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Creates a NATIVE stream. Native streams can sample data directly from an
* opaque platform object such as a SurfaceTexture on Android.
*
* @param stream An opaque native stream handle. e.g.: on Android this is an
* `android/graphics/SurfaceTexture` JNI jobject. The wrap mode must
* be CLAMP_TO_EDGE.
*
* @return This Builder, for chaining calls.
*/
Builder& stream(void* stream) noexcept;
/**
* Creates a TEXTURE_ID stream. This will sample data from the supplied
* external texture and copy it into an internal private texture.
*
* @param externalTextureId An opaque texture id (typically a GLuint created with glGenTextures)
* In a context shared with filament. In that case this texture's
* target must be GL_TEXTURE_EXTERNAL_OES and the wrap mode must
* be CLAMP_TO_EDGE.
*
* @return This Builder, for chaining calls.
*
* @see Texture::setExternalStream()
* @deprecated this method existed only for ARCore which doesn't need this anymore, use Texture::import() instead.
*/
UTILS_DEPRECATED
Builder& stream(intptr_t externalTextureId) noexcept;
/**
*
* @param width initial width of the incoming stream. Whether this value is used is
* stream dependent. On Android, it must be set when using
* Builder::stream(long externalTextureId).
*
* @return This Builder, for chaining calls.
*/
Builder& width(uint32_t width) noexcept;
/**
*
* @param height initial height of the incoming stream. Whether this value is used is
* stream dependent. On Android, it must be set when using
* Builder::stream(long externalTextureId).
*
* @return This Builder, for chaining calls.
*/
Builder& height(uint32_t height) noexcept;
/**
* Creates the Stream object and returns a pointer to it.
*
* @param engine Reference to the filament::Engine to associate this Stream with.
*
* @return pointer to the newly created object, or nullptr if the stream couldn't be created.
*/
Stream* build(Engine& engine);
private:
friend class FStream;
};
/**
* Indicates whether this stream is a NATIVE stream, TEXTURE_ID stream, or ACQUIRED stream.
*/
StreamType getStreamType() const noexcept;
/**
* Updates an ACQUIRED stream with an image that is guaranteed to be used in the next frame.
*
* This method tells Filament to immediately "acquire" the image and trigger a callback
* when it is done with it. This should be called by the user outside of beginFrame / endFrame,
* and should be called only once per frame. If the user pushes images to the same stream
* multiple times in a single frame, only the final image is honored, but all callbacks are
* invoked.
*
* This method should be called on the same thread that calls Renderer::beginFrame, which is
* also where the callback is invoked. This method can only be used for streams that were
* constructed without calling the `stream` method on the builder.
*
* @see Stream for more information about NATIVE, TEXTURE_ID, and ACQUIRED configurations.
*
* @param image Pointer to AHardwareBuffer, casted to void* since this is a public header.
* @param callback This is triggered by Filament when it wishes to release the image.
* It callback tales two arguments: the AHardwareBuffer and the userdata.
* @param userdata Optional closure data. Filament will pass this into the callback when it
* releases the image.
*/
void setAcquiredImage(void* image, Callback callback, void* userdata) noexcept;
/**
* Updates the size of the incoming stream. Whether this value is used is
* stream dependent. On Android, it must be set when using
* Builder::stream(long externalTextureId).
*
* @param width new width of the incoming stream
* @param height new height of the incoming stream
*/
void setDimensions(uint32_t width, uint32_t height) noexcept;
/**
* Read-back the content of the last frame of a Stream since the last call to
* Renderer.beginFrame().
*
* The Stream must be of type externalTextureId. This function is a no-op otherwise.
*
* @param xoffset Left offset of the sub-region to read back.
* @param yoffset Bottom offset of the sub-region to read back.
* @param width Width of the sub-region to read back.
* @param height Height of the sub-region to read back.
* @param buffer Client-side buffer where the read-back will be written.
*
* The following format are always supported:
* - PixelBufferDescriptor::PixelDataFormat::RGBA
* - PixelBufferDescriptor::PixelDataFormat::RGBA_INTEGER
*
* The following types are always supported:
* - PixelBufferDescriptor::PixelDataType::UBYTE
* - PixelBufferDescriptor::PixelDataType::UINT
* - PixelBufferDescriptor::PixelDataType::INT
* - PixelBufferDescriptor::PixelDataType::FLOAT
*
* Other combination of format/type may be supported. If a combination is
* not supported, this operation may fail silently. Use a DEBUG build
* to get some logs about the failure.
*
* Stream buffer User buffer (PixelBufferDescriptor&)
* +--------------------+
* | | .stride .alignment
* | | ----------------------->-->
* | | O----------------------+--+ low addresses
* | | | | | |
* | w | | | .top | |
* | <---------> | | V | |
* | +---------+ | | +---------+ | |
* | | ^ | | ======> | | | | |
* | x | h| | | |.left| | | |
* +------>| v | | +---->| | | |
* | +.........+ | | +.........+ | |
* | ^ | | | |
* | y | | +----------------------+--+ high addresses
* O------------+-------+
*
* Typically readPixels() will be called after Renderer.beginFrame().
*
* After issuing this method, the callback associated with `buffer` will be invoked on the
* main thread, indicating that the read-back has completed. Typically, this will happen
* after multiple calls to beginFrame(), render(), endFrame().
*
* It is also possible to use a Fence to wait for the read-back.
*
* @remark
* readPixels() is intended for debugging and testing. It will impact performance significantly.
*/
void readPixels(uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height,
backend::PixelBufferDescriptor&& buffer) noexcept;
/**
* Returns the presentation time of the currently displayed frame in nanosecond.
*
* This value can change at any time.
*
* @return timestamp in nanosecond.
*/
int64_t getTimestamp() const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_STREAM_H

230
ios/include/filament/SwapChain.h Normal file
View File

@@ -0,0 +1,230 @@
/*
* Copyright (C) 2017 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.
*/
#ifndef TNT_FILAMENT_SWAPCHAIN_H
#define TNT_FILAMENT_SWAPCHAIN_H
#include <filament/FilamentAPI.h>
#include <backend/DriverEnums.h>
#include <backend/PresentCallable.h>
#include <utils/compiler.h>
namespace filament {
/**
* A swap chain represents an Operating System's *native* renderable surface.
*
* Typically it's a native window or a view. Because a SwapChain is initialized from a
* native object, it is given to filament as a `void *`, which must be of the proper type
* for each platform filament is running on.
*
* \code
* SwapChain* swapChain = engine->createSwapChain(nativeWindow);
* \endcode
*
* When Engine::create() is used without specifying a Platform, the `nativeWindow`
* parameter above must be of type:
*
* Platform | nativeWindow type
* :---------------|:----------------------------:
* Android | ANativeWindow*
* macOS - OpenGL | NSView*
* macOS - Metal | CAMetalLayer*
* iOS - OpenGL | CAEAGLLayer*
* iOS - Metal | CAMetalLayer*
* X11 | Window
* Windows | HWND
*
* Otherwise, the `nativeWindow` is defined by the concrete implementation of Platform.
*
*
* Examples:
*
* Android
* -------
*
* On Android, an `ANativeWindow*` can be obtained from a Java `Surface` object using:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* #include <android/native_window_jni.h>
* // parameters
* // env: JNIEnv*
* // surface: jobject
* ANativeWindow* win = ANativeWindow_fromSurface(env, surface);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* \warning
* Don't use reflection to access the `mNativeObject` field, it won't work.
*
* A `Surface` can be retrieved from a `SurfaceView` or `SurfaceHolder` easily using
* `SurfaceHolder.getSurface()` and/or `SurfaceView.getHolder()`.
*
* \note
* To use a `TextureView` as a SwapChain, it is necessary to first get its `SurfaceTexture`,
* for instance using `TextureView.SurfaceTextureListener` and then create a `Surface`:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
* // using a TextureView.SurfaceTextureListener:
* public void onSurfaceTextureAvailable(SurfaceTexture surfaceTexture, int width, int height) {
* mSurface = new Surface(surfaceTexture);
* // mSurface can now be used in JNI to create an ANativeWindow.
* }
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Linux
* -----
*
* Example using SDL:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* SDL_SysWMinfo wmi;
* SDL_VERSION(&wmi.version);
* SDL_GetWindowWMInfo(sdlWindow, &wmi);
* Window nativeWindow = (Window) wmi.info.x11.window;
*
* using namespace filament;
* Engine* engine = Engine::create();
* SwapChain* swapChain = engine->createSwapChain((void*) nativeWindow);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* Windows
* -------
*
* Example using SDL:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* SDL_SysWMinfo wmi;
* SDL_VERSION(&wmi.version);
* ASSERT_POSTCONDITION(SDL_GetWindowWMInfo(sdlWindow, &wmi), "SDL version unsupported!");
* HDC nativeWindow = (HDC) wmi.info.win.hdc;
*
* using namespace filament;
* Engine* engine = Engine::create();
* SwapChain* swapChain = engine->createSwapChain((void*) nativeWindow);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* OSX
* ---
*
* On OSX, any `NSView` can be used *directly* as a `nativeWindow` with createSwapChain().
*
* Example using SDL/Objective-C:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.mm}
* #include <filament/Engine.h>
*
* #include <Cocoa/Cocoa.h>
* #include <SDL_syswm.h>
*
* SDL_SysWMinfo wmi;
* SDL_VERSION(&wmi.version);
* NSWindow* win = (NSWindow*) wmi.info.cocoa.window;
* NSView* view = [win contentView];
* void* nativeWindow = view;
*
* using namespace filament;
* Engine* engine = Engine::create();
* SwapChain* swapChain = engine->createSwapChain(nativeWindow);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* @see Engine
*/
class UTILS_PUBLIC SwapChain : public FilamentAPI {
public:
using FrameScheduledCallback = backend::FrameScheduledCallback;
using FrameCompletedCallback = backend::FrameCompletedCallback;
static const uint64_t CONFIG_TRANSPARENT = backend::SWAP_CHAIN_CONFIG_TRANSPARENT;
/**
* This flag indicates that the swap chain may be used as a source surface
* for reading back render results. This config must be set when creating
* any swap chain that will be used as the source for a blit operation.
*
* @see
* Renderer.copyFrame()
*/
static const uint64_t CONFIG_READABLE = backend::SWAP_CHAIN_CONFIG_READABLE;
/**
* Indicates that the native X11 window is an XCB window rather than an XLIB window.
* This is ignored on non-Linux platforms and in builds that support only one X11 API.
*/
static const uint64_t CONFIG_ENABLE_XCB = backend::SWAP_CHAIN_CONFIG_ENABLE_XCB;
/**
* Indicates that the native window is a CVPixelBufferRef.
*
* This is only supported by the Metal backend. The CVPixelBuffer must be in the
* kCVPixelFormatType_32BGRA format.
*
* It is not necessary to add an additional retain call before passing the pixel buffer to
* Filament. Filament will call CVPixelBufferRetain during Engine::createSwapChain, and
* CVPixelBufferRelease when the swap chain is destroyed.
*/
static const uint64_t CONFIG_APPLE_CVPIXELBUFFER =
backend::SWAP_CHAIN_CONFIG_APPLE_CVPIXELBUFFER;
void* getNativeWindow() const noexcept;
/**
* FrameScheduledCallback is a callback function that notifies an application when Filament has
* completed processing a frame and that frame is ready to be scheduled for presentation.
*
* Typically, Filament is responsible for scheduling the frame's presentation to the SwapChain.
* If a SwapChain::FrameScheduledCallback is set, however, the application bares the
* responsibility of scheduling a frame for presentation by calling the backend::PresentCallable
* passed to the callback function. Currently this functionality is only supported by the Metal
* backend.
*
* A FrameScheduledCallback can be set on an individual SwapChain through
* SwapChain::setFrameScheduledCallback. If the callback is set, then the SwapChain will *not*
* automatically schedule itself for presentation. Instead, the application must call the
* PresentCallable passed to the FrameScheduledCallback.
*
* @param callback A callback, or nullptr to unset.
* @param user An optional pointer to user data passed to the callback function.
*
* @remark Only Filament's Metal backend supports PresentCallables and frame callbacks. Other
* backends ignore the callback (which will never be called) and proceed normally.
*
* @remark The SwapChain::FrameScheduledCallback is called on an arbitrary thread.
*
* @see PresentCallable
*/
void setFrameScheduledCallback(FrameScheduledCallback callback, void* user = nullptr);
/**
* FrameCompletedCallback is a callback function that notifies an application when a frame's
* contents have completed rendering on the GPU.
*
* Use SwapChain::setFrameCompletedCallback to set a callback on an individual SwapChain. Each
* time a frame completes GPU rendering, the callback will be called with optional user data.
*
* The FrameCompletedCallback is guaranteed to be called on the main Filament thread.
*
* @param callback A callback, or nullptr to unset.
* @param user An optional pointer to user data passed to the callback function.
*
* @remark Only Filament's Metal backend supports frame callbacks. Other backends ignore the
* callback (which will never be called) and proceed normally.
*/
void setFrameCompletedCallback(FrameCompletedCallback callback, void* user = nullptr);
};
} // namespace filament
#endif // TNT_FILAMENT_SWAPCHAIN_H

517
ios/include/filament/Texture.h Normal file
View File

@@ -0,0 +1,517 @@
/*
* 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_TEXTURE_H
#define TNT_FILAMENT_TEXTURE_H
#include <filament/FilamentAPI.h>
#include <backend/DriverEnums.h>
#include <backend/PixelBufferDescriptor.h>
#include <utils/compiler.h>
#include <stddef.h>
namespace filament {
class FTexture;
class Engine;
class Stream;
/**
* Texture
*
* The Texture class supports:
* - 2D textures
* - 3D textures
* - Cube maps
* - mip mapping
*
*
* Creation and destruction
* ========================
*
* A Texture object is created using the Texture::Builder and destroyed by calling
* Engine::destroy(const Texture*).
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
* filament::Engine* engine = filament::Engine::create();
*
* filament::Texture* texture = filament::Texture::Builder()
* .width(64)
* .height(64)
* .build(*engine);
*
* engine->destroy(texture);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
*/
class UTILS_PUBLIC Texture : public FilamentAPI {
struct BuilderDetails;
public:
static constexpr const size_t BASE_LEVEL = 0;
using PixelBufferDescriptor = backend::PixelBufferDescriptor; //!< Geometry of a pixel buffer
using Sampler = backend::SamplerType; //!< Type of sampler
using InternalFormat = backend::TextureFormat; //!< Internal texel format
using CubemapFace = backend::TextureCubemapFace; //!< Cube map faces
using Format = backend::PixelDataFormat; //!< Pixel color format
using Type = backend::PixelDataType; //!< Pixel data format
using CompressedType = backend::CompressedPixelDataType; //!< Compressed pixel data format
using FaceOffsets = backend::FaceOffsets; //!< Cube map faces offsets
using Usage = backend::TextureUsage; //!< Usage affects texel layout
using Swizzle = backend::TextureSwizzle; //!< Texture swizzle
/** @return whether a backend supports a particular format. */
static bool isTextureFormatSupported(Engine& engine, InternalFormat format) noexcept;
/** @return whether a backend supports texture swizzling. */
static bool isTextureSwizzleSupported(Engine& engine) noexcept;
static size_t computeTextureDataSize(Texture::Format format, Texture::Type type,
size_t stride, size_t height, size_t alignment) noexcept;
/**
* Options for environment prefiltering into reflection map
*
* @see generatePrefilterMipmap()
*/
struct PrefilterOptions {
uint16_t sampleCount = 8; //!< sample count used for filtering
bool mirror = true; //!< whether the environment must be mirrored
private:
UTILS_UNUSED uintptr_t reserved[3] = {};
};
//! Use Builder to construct a Texture object instance
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Specifies the width in texels of the texture. Doesn't need to be a power-of-two.
* @param width Width of the texture in texels (default: 1).
* @return This Builder, for chaining calls.
*/
Builder& width(uint32_t width) noexcept;
/**
* Specifies the height in texels of the texture. Doesn't need to be a power-of-two.
* @param height Height of the texture in texels (default: 1).
* @return This Builder, for chaining calls.
*/
Builder& height(uint32_t height) noexcept;
/**
* Specifies the depth in texels of the texture. Doesn't need to be a power-of-two.
* The depth controls the number of layers in a 2D array texture. Values greater than 1
* effectively create a 3D texture.
* @param depth Depth of the texture in texels (default: 1).
* @return This Builder, for chaining calls.
* @attention This Texture instance must use Sampler::SAMPLER_3D or Sampler::SAMPLER_2D_ARRAY or it has no effect.
*/
Builder& depth(uint32_t depth) noexcept;
/**
* Specifies the numbers of mip map levels.
* This creates a mip-map pyramid. The maximum number of levels a texture can have is
* such that max(width, height, level) / 2^MAX_LEVELS = 1
* @param levels Number of mipmap levels for this texture.
* @return This Builder, for chaining calls.
*/
Builder& levels(uint8_t levels) noexcept;
/**
* Specifies the type of sampler to use.
* @param target Sampler type
* @return This Builder, for chaining calls.
* @see Sampler
*/
Builder& sampler(Sampler target) noexcept;
/**
* Specifies the *internal* format of this texture.
*
* The internal format specifies how texels are stored (which may be different from how
* they're specified in setImage()). InternalFormat specifies both the color components
* and the data type used.
*
* @param format Format of the texture's texel.
* @return This Builder, for chaining calls.
* @see InternalFormat, setImage
*/
Builder& format(InternalFormat format) noexcept;
/**
* Specifies if the texture will be used as a render target attachment.
*
* If the texture is potentially rendered into, it may require a different memory layout,
* which needs to be known during construction.
*
* @param usage Defaults to Texture::Usage::DEFAULT; c.f. Texture::Usage::COLOR_ATTACHMENT.
* @return This Builder, for chaining calls.
*/
Builder& usage(Usage usage) noexcept;
/**
* Specifies how a texture's channels map to color components
*
* Texture Swizzle is only supported is isTextureSwizzleSupported() returns true.
*
* @param r texture channel for red component
* @param g texture channel for green component
* @param b texture channel for blue component
* @param a texture channel for alpha component
* @return This Builder, for chaining calls.
* @see Texture::isTextureSwizzleSupported()
*/
Builder& swizzle(Swizzle r, Swizzle g, Swizzle b, Swizzle a) noexcept;
/**
* Creates the Texture object and returns a pointer to it.
*
* @param engine Reference to the filament::Engine to associate this Texture with.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*/
Texture* build(Engine& engine);
/* no user serviceable parts below */
/**
* Specify a native texture to import as a Filament texture.
*
* The texture id is backend-specific:
* - OpenGL: GLuint texture ID
* - Metal: id<MTLTexture>
*
* With Metal, the id<MTLTexture> object should be cast to an intptr_t using
* CFBridgingRetain to transfer ownership to Filament. Filament will release ownership of
* the texture object when the Filament texture is destroyed.
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
* id <MTLTexture> metalTexture = ...
* filamentTexture->import((intptr_t) CFBridgingRetain(metalTexture));
* // free to release metalTexture
*
* // after using texture:
* engine->destroy(filamentTexture); // metalTexture is released
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* @warning This method should be used as a last resort. This API is subject to change or
* removal.
*
* @param id a backend specific texture identifier
*
* @return This Builder, for chaining calls.
*/
Builder& import(intptr_t id) noexcept;
private:
friend class FTexture;
};
/**
* Returns the width of a 2D or 3D texture level
* @param level texture level.
* @return Width in texel of the specified \p level, clamped to 1.
* @attention If this texture is using Sampler::SAMPLER_EXTERNAL, the dimension
* of the texture are unknown and this method always returns whatever was set on the Builder.
*/
size_t getWidth(size_t level = BASE_LEVEL) const noexcept;
/**
* Returns the height of a 2D or 3D texture level
* @param level texture level.
* @return Height in texel of the specified \p level, clamped to 1.
* @attention If this texture is using Sampler::SAMPLER_EXTERNAL, the dimension
* of the texture are unknown and this method always returns whatever was set on the Builder.
*/
size_t getHeight(size_t level = BASE_LEVEL) const noexcept;
/**
* Returns the depth of a 3D texture level
* @param level texture level.
* @return Depth in texel of the specified \p level, clamped to 1.
* @attention If this texture is using Sampler::SAMPLER_EXTERNAL, the dimension
* of the texture are unknown and this method always returns whatever was set on the Builder.
*/
size_t getDepth(size_t level = BASE_LEVEL) const noexcept;
/**
* Returns the maximum number of levels this texture can have.
* @return maximum number of levels this texture can have.
* @attention If this texture is using Sampler::SAMPLER_EXTERNAL, the dimension
* of the texture are unknown and this method always returns whatever was set on the Builder.
*/
size_t getLevels() const noexcept;
/**
* Return this texture Sampler as set by Builder::sampler().
* @return this texture Sampler as set by Builder::sampler()
*/
Sampler getTarget() const noexcept;
/**
* Return this texture InternalFormat as set by Builder::format().
* @return this texture InternalFormat as set by Builder::format().
*/
InternalFormat getFormat() const noexcept;
/**
* Specify the image of a 2D texture for a level.
*
* @param engine Engine this texture is associated to.
* @param level Level to set the image for.
* @param buffer Client-side buffer containing the image to set.
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention \p level must be less than getLevels().
* @attention \p buffer's Texture::Format must match that of getFormat().
* @attention This Texture instance must use Sampler::SAMPLER_2D or
* Sampler::SAMPLER_EXTERNAL. IF the later is specified
* and external textures are supported by the driver implementation,
* this method will have no effect, otherwise it will behave as if the
* texture was specified with driver::SamplerType::SAMPLER_2D.
*
* @note
* This is equivalent to calling:
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* setImage(engine, level, 0, 0, getWidth(level), getHeight(level), buffer);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* @see Builder::sampler()
*/
void setImage(Engine& engine, size_t level, PixelBufferDescriptor&& buffer) const;
/**
* Updates a sub-image of a 2D texture for a level.
*
* @param engine Engine this texture is associated to.
* @param level Level to set the image for.
* @param xoffset Left offset of the sub-region to update.
* @param yoffset Bottom offset of the sub-region to update.
* @param width Width of the sub-region to update.
* @param height Height of the sub-region to update.
* @param buffer Client-side buffer containing the image to set.
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention \p level must be less than getLevels().
* @attention \p buffer's Texture::Format must match that of getFormat().
* @attention This Texture instance must use Sampler::SAMPLER_2D or
* Sampler::SAMPLER_EXTERNAL. IF the later is specified
* and external textures are supported by the driver implementation,
* this method will have no effect, otherwise it will behave as if the
* texture was specified with Sampler::SAMPLER_2D.
*
* @see Builder::sampler()
*/
void setImage(Engine& engine, size_t level,
uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height,
PixelBufferDescriptor&& buffer) const;
/**
* Updates a sub-image of a 3D texture or 2D texture array for a level.
*
* @param engine Engine this texture is associated to.
* @param level Level to set the image for.
* @param xoffset Left offset of the sub-region to update.
* @param yoffset Bottom offset of the sub-region to update.
* @param zoffset Depth offset of the sub-region to update.
* @param width Width of the sub-region to update.
* @param height Height of the sub-region to update.
* @param depth Depth of the sub-region to update.
* @param buffer Client-side buffer containing the image to set.
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention \p level must be less than getLevels().
* @attention \p buffer's Texture::Format must match that of getFormat().
* @attention This Texture instance must use Sampler::SAMPLER_3D or Sampler::SAMPLER_2D_array.
*
* @see Builder::sampler()
*/
void setImage(Engine& engine, size_t level,
uint32_t xoffset, uint32_t yoffset, uint32_t zoffset,
uint32_t width, uint32_t height, uint32_t depth,
PixelBufferDescriptor&& buffer) const;
/**
* Specify all six images of a cube map level.
*
* This method follows exactly the OpenGL conventions.
*
* @param engine Engine this texture is associated to.
* @param level Level to set the image for.
* @param buffer Client-side buffer containing the images to set.
* @param faceOffsets Offsets in bytes into \p buffer for all six images. The offsets
* are specified in the following order: +x, -x, +y, -y, +z, -z
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention \p level must be less than getLevels().
* @attention \p buffer's Texture::Format must match that of getFormat().
* @attention This Texture instance must use Sampler::SAMPLER_CUBEMAP or it has no effect
*
* @see Texture::CubemapFace, Builder::sampler()
*/
void setImage(Engine& engine, size_t level,
PixelBufferDescriptor&& buffer, const FaceOffsets& faceOffsets) const;
/**
* Specify the external image to associate with this Texture. Typically the external
* image is OS specific, and can be a video or camera frame.
* There are many restrictions when using an external image as a texture, such as:
* - only the level of detail (lod) 0 can be specified
* - only nearest or linear filtering is supported
* - the size and format of the texture is defined by the external image
* - only the CLAMP_TO_EDGE wrap mode is supported
*
* @param engine Engine this texture is associated to.
* @param image An opaque handle to a platform specific image. Supported types are
* eglImageOES on Android and CVPixelBufferRef on iOS.
*
* On iOS the following pixel formats are supported:
* - kCVPixelFormatType_32BGRA
* - kCVPixelFormatType_420YpCbCr8BiPlanarFullRange
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention This Texture instance must use Sampler::SAMPLER_EXTERNAL or it has no effect
*
* @see Builder::sampler()
*
*/
void setExternalImage(Engine& engine, void* image) noexcept;
/**
* Specify the external image and plane to associate with this Texture. Typically the external
* image is OS specific, and can be a video or camera frame. When using this method, the
* external image must be a planar type (such as a YUV camera frame). The plane parameter
* selects which image plane is bound to this texture.
*
* A single external image can be bound to different Filament textures, with each texture
* associated with a separate plane:
*
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* textureA->setExternalImage(engine, image, 0);
* textureB->setExternalImage(engine, image, 1);
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* There are many restrictions when using an external image as a texture, such as:
* - only the level of detail (lod) 0 can be specified
* - only nearest or linear filtering is supported
* - the size and format of the texture is defined by the external image
* - only the CLAMP_TO_EDGE wrap mode is supported
*
* @param engine Engine this texture is associated to.
* @param image An opaque handle to a platform specific image. Supported types are
* eglImageOES on Android and CVPixelBufferRef on iOS.
* @param plane The plane index of the external image to associate with this texture.
*
* This method is only meaningful on iOS with
* kCVPixelFormatType_420YpCbCr8BiPlanarFullRange images. On platforms
* other than iOS, this method is a no-op.
*/
void setExternalImage(Engine& engine, void* image, size_t plane) noexcept;
/**
* Specify the external stream to associate with this Texture. Typically the external
* stream is OS specific, and can be a video or camera stream.
* There are many restrictions when using an external stream as a texture, such as:
* - only the level of detail (lod) 0 can be specified
* - only nearest or linear filtering is supported
* - the size and format of the texture is defined by the external stream
*
* @param engine Engine this texture is associated to.
* @param stream A Stream object
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention This Texture instance must use Sampler::SAMPLER_EXTERNAL or it has no effect
*
* @see Builder::sampler(), Stream
*
*/
void setExternalStream(Engine& engine, Stream* stream) noexcept;
/**
* Generates all the mipmap levels automatically. This requires the texture to have a
* color-renderable format.
*
* @param engine Engine this texture is associated to.
*
* @attention \p engine must be the instance passed to Builder::build()
* @attention This Texture instance must NOT use Sampler::SAMPLER_CUBEMAP or it has no effect
*/
void generateMipmaps(Engine& engine) const noexcept;
/**
* Creates a reflection map from an environment map.
*
* This is a utility function that replaces calls to Texture::setImage().
* The provided environment map is processed and all mipmap levels are populated. The
* processing is similar to the offline tool `cmgen` as a lower quality setting.
*
* This function is intended to be used when the environment cannot be processed offline,
* for instance if it's generated at runtime.
*
* The source data must obey to some constraints:
* - the data type must be PixelDataFormat::RGB
* - the data format must be one of
* - PixelDataType::FLOAT
* - PixelDataType::HALF
*
* The current texture must be a cubemap
*
* The reflections cubemap's internal format cannot be a compressed format.
*
* The reflections cubemap's dimension must be a power-of-two.
*
* @warning This operation is computationally intensive, especially with large environments and
* is currently synchronous. Expect about 1ms for a 16x16 cubemap.
*
* @param engine Reference to the filament::Engine to associate this IndirectLight with.
* @param buffer Client-side buffer containing the images to set.
* @param faceOffsets Offsets in bytes into \p buffer for all six images. The offsets
* are specified in the following order: +x, -x, +y, -y, +z, -z
* @param options Optional parameter to controlling user-specified quality and options.
*
* @exception utils::PreConditionPanic if the source data constraints are not respected.
*
*/
void generatePrefilterMipmap(Engine& engine,
PixelBufferDescriptor&& buffer, const FaceOffsets& faceOffsets,
PrefilterOptions const* options = nullptr);
};
} // namespace filament
#endif // TNT_FILAMENT_TEXTURE_H

205
ios/include/filament/TextureSampler.h Normal file
View File

@@ -0,0 +1,205 @@
/*
* 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_TEXTURESAMPLER_H
#define TNT_FILAMENT_TEXTURESAMPLER_H
#include <backend/DriverEnums.h>
#include <utils/compiler.h>
#include <math.h>
namespace filament {
/**
* TextureSampler defines how a texture is accessed.
*/
class UTILS_PUBLIC TextureSampler {
public:
using WrapMode = backend::SamplerWrapMode;
using MinFilter = backend::SamplerMinFilter;
using MagFilter = backend::SamplerMagFilter;
using CompareMode = backend::SamplerCompareMode;
using CompareFunc = backend::SamplerCompareFunc;
/**
* Creates a default sampler.
* The default parameters are:
* - filterMag : NEAREST
* - filterMin : NEAREST
* - wrapS : CLAMP_TO_EDGE
* - wrapT : CLAMP_TO_EDGE
* - wrapR : CLAMP_TO_EDGE
* - compareMode : NONE
* - compareFunc : Less or equal
* - no anisotropic filtering
*/
TextureSampler() noexcept = default;
TextureSampler(const TextureSampler& rhs) noexcept = default;
TextureSampler& operator=(const TextureSampler& rhs) noexcept = default;
/**
* Creates a TextureSampler with the default parameters but setting the filtering and wrap modes.
* @param minMag filtering for both minification and magnification
* @param str wrapping mode for all texture coordinate axes
*/
explicit TextureSampler(MagFilter minMag, WrapMode str = WrapMode::CLAMP_TO_EDGE) noexcept {
mSamplerParams.filterMin = MinFilter(minMag);
mSamplerParams.filterMag = minMag;
mSamplerParams.wrapS = str;
mSamplerParams.wrapT = str;
mSamplerParams.wrapR = str;
}
/**
* Creates a TextureSampler with the default parameters but setting the filtering and wrap modes.
* @param min filtering for minification
* @param mag filtering for magnification
* @param str wrapping mode for all texture coordinate axes
*/
TextureSampler(MinFilter min, MagFilter mag, WrapMode str = WrapMode::CLAMP_TO_EDGE) noexcept {
mSamplerParams.filterMin = min;
mSamplerParams.filterMag = mag;
mSamplerParams.wrapS = str;
mSamplerParams.wrapT = str;
mSamplerParams.wrapR = str;
}
/**
* Creates a TextureSampler with the default parameters but setting the filtering and wrap modes.
* @param min filtering for minification
* @param mag filtering for magnification
* @param s wrap mode for the s (horizontal)texture coordinate
* @param t wrap mode for the t (vertical) texture coordinate
* @param r wrap mode for the r (depth) texture coordinate
*/
TextureSampler(MinFilter min, MagFilter mag, WrapMode s, WrapMode t, WrapMode r) noexcept {
mSamplerParams.filterMin = min;
mSamplerParams.filterMag = mag;
mSamplerParams.wrapS = s;
mSamplerParams.wrapT = t;
mSamplerParams.wrapR = r;
}
/**
* Creates a TextureSampler with the default parameters but setting the compare mode and function
* @param mode Compare mode
* @param func Compare function
*/
explicit TextureSampler(CompareMode mode, CompareFunc func = CompareFunc::LE) noexcept {
mSamplerParams.compareMode = mode;
mSamplerParams.compareFunc = func;
}
/**
* Sets the minification filter
* @param v Minification filter
*/
void setMinFilter(MinFilter v) noexcept {
mSamplerParams.filterMin = v;
}
/**
* Sets the magnification filter
* @param v Magnification filter
*/
void setMagFilter(MagFilter v) noexcept {
mSamplerParams.filterMag = v;
}
/**
* Sets the wrap mode for the s (horizontal) texture coordinate
* @param v wrap mode
*/
void setWrapModeS(WrapMode v) noexcept {
mSamplerParams.wrapS = v;
}
/**
* Sets the wrap mode for the t (vertical) texture coordinate
* @param v wrap mode
*/
void setWrapModeT(WrapMode v) noexcept {
mSamplerParams.wrapT = v;
}
/**
* Sets the wrap mode for the r (depth, for 3D textures) texture coordinate
* @param v wrap mode
*/
void setWrapModeR(WrapMode v) noexcept {
mSamplerParams.wrapR = v;
}
/**
* This controls anisotropic filtering.
* @param anisotropy Amount of anisotropy, should be a power-of-two. The default is 0.
* The maximum permissible value is 7.
*/
void setAnisotropy(float anisotropy) noexcept {
const int log2 = ilogbf(anisotropy > 0 ? anisotropy : -anisotropy);
mSamplerParams.anisotropyLog2 = uint8_t(log2 < 7 ? log2 : 7);
}
/**
* Sets the compare mode and function.
* @param mode Compare mode
* @param func Compare function
*/
void setCompareMode(CompareMode mode, CompareFunc func = CompareFunc::LE) noexcept {
mSamplerParams.compareMode = mode;
mSamplerParams.compareFunc = func;
}
//! returns the minification filter value
MinFilter getMinFilter() const noexcept { return mSamplerParams.filterMin; }
//! returns the magnification filter value
MagFilter getMagFilter() const noexcept { return mSamplerParams.filterMag; }
//! returns the s-coordinate wrap mode (horizontal)
WrapMode getWrapModeS() const noexcept { return mSamplerParams.wrapS; }
//! returns the t-coordinate wrap mode (vertical)
WrapMode getWrapModeT() const noexcept { return mSamplerParams.wrapT; }
//! returns the r-coordinate wrap mode (depth)
WrapMode getWrapModeR() const noexcept { return mSamplerParams.wrapR; }
//! returns the anisotropy value
float getAnisotropy() const noexcept { return float(1u << mSamplerParams.anisotropyLog2); }
//! returns the compare mode
CompareMode getCompareMode() const noexcept { return mSamplerParams.compareMode; }
//! returns the compare function
CompareFunc getCompareFunc() const noexcept { return mSamplerParams.compareFunc; }
// no user-serviceable parts below...
backend::SamplerParams getSamplerParams() const noexcept { return mSamplerParams; }
private:
backend::SamplerParams mSamplerParams{};
};
} // namespace filament
#endif // TNT_FILAMENT_TEXTURESAMPLER_H

235
ios/include/filament/ToneMapper.h Normal file
View File

@@ -0,0 +1,235 @@
/*
* Copyright (C) 2020 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.
*/
#ifndef TNT_FILAMENT_TONE_MAPPER_H
#define TNT_FILAMENT_TONE_MAPPER_H
#include <utils/compiler.h>
#include <math/mathfwd.h>
namespace filament {
/**
* Interface for tone mapping operators. A tone mapping operator, or tone mapper,
* is responsible for compressing the dynamic range of the rendered scene to a
* dynamic range suitable for display.
*
* In Filament, tone mapping is a color grading step. ToneMapper instances are
* created and passed to the ColorGrading::Builder to produce a 3D LUT that will
* be used during post-processing to prepare the final color buffer for display.
*
* Filament provides several default tone mapping operators that fall into three
* categories:
*
* - Configurable tone mapping operators
* - GenericToneMapper
* - Fixed-aesthetic tone mapping operators
* - ACESToneMapper
* - ACESLegacyToneMapper
* - FilmicToneMapper
* - Debug/validation tone mapping operators
* - LinearToneMapper
* - DisplayRangeToneMapper
*
* You can create custom tone mapping operators by subclassing ToneMapper.
*/
struct UTILS_PUBLIC ToneMapper {
ToneMapper() noexcept;
virtual ~ToneMapper() noexcept;
/**
* Maps an open domain (or "scene referred" values) color value to display
* domain (or "display referred") color value. Both the input and output
* color values are defined in the Rec.2020 color space, with no transfer
* function applied ("linear Rec.2020").
*
* @param c Input color to tone map, in the Rec.2020 color space with no
* transfer function applied ("linear")
*
* @return A tone mapped color in the Rec.2020 color space, with no transfer
* function applied ("linear")
*/
virtual math::float3 operator()(math::float3 c) const noexcept = 0;
};
/**
* Linear tone mapping operator that returns the input color but clamped to
* the 0..1 range. This operator is mostly useful for debugging.
*/
struct UTILS_PUBLIC LinearToneMapper final : public ToneMapper {
LinearToneMapper() noexcept;
~LinearToneMapper() noexcept final;
math::float3 operator()(math::float3 c) const noexcept;
};
/**
* ACES tone mapping operator. This operator is an implementation of the
* ACES Reference Rendering Transform (RRT) combined with the Output Device
* Transform (ODT) for sRGB monitors (dim surround, 100 nits).
*/
struct UTILS_PUBLIC ACESToneMapper final : public ToneMapper {
ACESToneMapper() noexcept;
~ACESToneMapper() noexcept final;
math::float3 operator()(math::float3 c) const noexcept;
};
/**
* ACES tone mapping operator, modified to match the perceived brightness
* of FilmicToneMapper. This operator is the same as ACESToneMapper but
* applies a brightness multiplier of ~1.6 to the input color value to
* target brighter viewing environments.
*/
struct UTILS_PUBLIC ACESLegacyToneMapper final : public ToneMapper {
ACESLegacyToneMapper() noexcept;
~ACESLegacyToneMapper() noexcept final;
math::float3 operator()(math::float3 c) const noexcept;
};
/**
* "Filmic" tone mapping operator. This tone mapper was designed to
* approximate the aesthetics of the ACES RRT + ODT for Rec.709
* and historically Filament's default tone mapping operator. It exists
* only for backward compatibility purposes and is not otherwise recommended.
*/
struct UTILS_PUBLIC FilmicToneMapper final : public ToneMapper {
FilmicToneMapper() noexcept;
~FilmicToneMapper() noexcept final;
math::float3 operator()(math::float3 x) const noexcept;
};
/**
* Generic tone mapping operator that gives control over the tone mapping
* curve. This operator can be used to control the aesthetics of the final
* image. This operator also allows to control the dynamic range of the
* scene referred values.
*
* The tone mapping curve is defined by 5 parameters:
* - contrast: controls the contrast of the curve
* - shoulder: controls the shoulder of the curve, i.e. how quickly scene
* referred values map to output white
* - midGrayIn: sets the input middle gray
* - midGrayOut: sets the output middle gray
* - hdrMax: defines the maximum input value that will be mapped to
* output white
*/
struct UTILS_PUBLIC GenericToneMapper final : public ToneMapper {
/**
* Builds a new generic tone mapper. The default values of the
* constructor parameters approximate an ACES tone mapping curve
* and the maximum input value is set to 10.0.
*
* @param contrast: controls the contrast of the curve, must be > 0.0, values
* in the range 0.5..2.0 are recommended.
* @param shoulder: controls the shoulder of the curve, i.e. how quickly scene
* referred values map to output white, between 0.0 and 1.0.
* @param midGrayIn: sets the input middle gray, between 0.0 and 1.0.
* @param midGrayOut: sets the output middle gray, between 0.0 and 1.0.
* @param hdrMax: defines the maximum input value that will be mapped to
* output white. Must be >= 1.0.
*/
GenericToneMapper(
float contrast = 1.585f,
float shoulder = 0.5f,
float midGrayIn = 0.18f,
float midGrayOut = 0.268f,
float hdrMax = 10.0f
) noexcept;
~GenericToneMapper() noexcept final;
GenericToneMapper(GenericToneMapper const&) = delete;
GenericToneMapper& operator=(GenericToneMapper const&) = delete;
GenericToneMapper(GenericToneMapper&& rhs) noexcept;
GenericToneMapper& operator=(GenericToneMapper& rhs) noexcept;
math::float3 operator()(math::float3 x) const noexcept;
/** Returns the contrast of the curve as a strictly positive value. */
float getContrast() const noexcept;
/** Returns how fast scene referred values map to output white as a value between 0.0 and 1.0. */
float getShoulder() const noexcept;
/** Returns the middle gray point for input values as a value between 0.0 and 1.0. */
float getMidGrayIn() const noexcept;
/** Returns the middle gray point for output values as a value between 0.0 and 1.0. */
float getMidGrayOut() const noexcept;
/** Returns the maximum input value that will map to output white, as a value >= 1.0. */
float getHdrMax() const noexcept;
/** Sets the contrast of the curve, must be > 0.0, values in the range 0.5..2.0 are recommended. */
void setContrast(float contrast) noexcept;
/** Sets how quickly scene referred values map to output white, between 0.0 and 1.0. */
void setShoulder(float shoulder) noexcept;
/** Sets the input middle gray, between 0.0 and 1.0. */
void setMidGrayIn(float midGrayIn) noexcept;
/** Sets the output middle gray, between 0.0 and 1.0. */
void setMidGrayOut(float midGrayOut) noexcept;
/** Defines the maximum input value that will be mapped to output white. Must be >= 1.0. */
void setHdrMax(float hdrMax) noexcept;
private:
struct Options;
Options* mOptions;
};
/**
* A tone mapper that converts the input HDR RGB color into one of 16 debug colors
* that represent the pixel's exposure. When the output is cyan, the input color
* represents middle gray (18% exposure). Every exposure stop above or below middle
* gray causes a color shift.
*
* The relationship between exposures and colors is:
*
* - -5EV black
* - -4EV darkest blue
* - -3EV darker blue
* - -2EV dark blue
* - -1EV blue
* - OEV cyan
* - +1EV dark green
* - +2EV green
* - +3EV yellow
* - +4EV yellow-orange
* - +5EV orange
* - +6EV bright red
* - +7EV red
* - +8EV magenta
* - +9EV purple
* - +10EV white
*
* This tone mapper is useful to validate and tweak scene lighting.
*/
struct UTILS_PUBLIC DisplayRangeToneMapper final : public ToneMapper {
DisplayRangeToneMapper() noexcept;
~DisplayRangeToneMapper() noexcept;
math::float3 operator()(math::float3 c) const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_TONE_MAPPER_H

310
ios/include/filament/TransformManager.h Normal file
View File

@@ -0,0 +1,310 @@
/*
* Copyright (C) 2017 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.
*/
#ifndef TNT_FILAMENT_TRANSFORMMANAGER_H
#define TNT_FILAMENT_TRANSFORMMANAGER_H
#include <filament/FilamentAPI.h>
#include <utils/compiler.h>
#include <utils/EntityInstance.h>
#include <math/mathfwd.h>
#include <iterator>
namespace utils {
class Entity;
} // namespace utils
namespace filament {
class FTransformManager;
/**
* TransformManager is used to add transform components to entities.
*
* A Transform component gives an entity a position and orientation in space in the coordinate
* space of its parent transform. The TransformManager takes care of computing the world-space
* transform of each component (i.e. its transform relative to the root).
*
* Creation and destruction
* ========================
*
* A transform component is created using TransformManager::create() and destroyed by calling
* TransformManager::destroy().
*
* ~~~~~~~~~~~{.cpp}
* filament::Engine* engine = filament::Engine::create();
* utils::Entity object = utils::EntityManager.get().create();
*
* auto& tcm = engine->getTransformManager();
*
* // create the transform component
* tcm.create(object);
*
* // set its transform
* auto i = tcm.getInstance(object);
* tcm.setTransform(i, mat4f::translation({ 0, 0, -1 }));
*
* // destroy the transform component
* tcm.destroy(object);
* ~~~~~~~~~~~
*
*/
class UTILS_PUBLIC TransformManager : public FilamentAPI {
public:
using Instance = utils::EntityInstance<TransformManager>;
class children_iterator : std::iterator<std::forward_iterator_tag, Instance> {
friend class FTransformManager;
TransformManager const& mManager;
Instance mInstance;
children_iterator(TransformManager const& mgr, Instance instance) noexcept
: mManager(mgr), mInstance(instance) { }
public:
children_iterator& operator++();
children_iterator operator++(int) { // NOLINT
children_iterator ret(*this);
++(*this);
return ret;
}
bool operator == (const children_iterator& other) const noexcept {
return mInstance == other.mInstance;
}
bool operator != (const children_iterator& other) const noexcept {
return mInstance != other.mInstance;
}
value_type operator*() const { return mInstance; }
};
/**
* Returns whether a particular Entity is associated with a component of this TransformManager
* @param e An Entity.
* @return true if this Entity has a component associated with this manager.
*/
bool hasComponent(utils::Entity e) const noexcept;
/**
* Gets an Instance representing the transform component associated with the given Entity.
* @param e An Entity.
* @return An Instance object, which represents the transform component associated with the Entity e.
* @note Use Instance::isValid() to make sure the component exists.
* @see hasComponent()
*/
Instance getInstance(utils::Entity e) const noexcept;
/**
* Enables or disable the accurate translation mode. Disabled by default.
*
* When accurate translation mode is active, the translation component of all transforms is
* maintained at double precision. This is only useful if the mat4 version of setTransform()
* is used, as well as getTransformAccurate().
*
* @param enable true to enable the accurate translation mode, false to disable.
*
* @see isAccurateTranslationsEnabled
* @see create(utils::Entity, Instance, const math::mat4&);
* @see setTransform(Instance, const math::mat4&)
* @see getTransformAccurate
* @see getWorldTransformAccurate
*/
void setAccurateTranslationsEnabled(bool enable) noexcept;
/**
* Returns whether the high precision translation mode is active.
* @return true if accurate translations mode is active, false otherwise
* @see setAccurateTranslationsEnabled
*/
bool isAccurateTranslationsEnabled() const noexcept;
/**
* Creates a transform component and associate it with the given entity.
* @param entity An Entity to associate a transform component to.
* @param parent The Instance of the parent transform, or Instance{} if no parent.
* @param localTransform The transform to initialize the transform component with.
* This is always relative to the parent.
*
* If this component already exists on the given entity, it is first destroyed as if
* destroy(utils::Entity e) was called.
*
* @see destroy()
*/
void create(utils::Entity entity, Instance parent, const math::mat4f& localTransform);
void create(utils::Entity entity, Instance parent, const math::mat4& localTransform); //!< \overload
void create(utils::Entity entity, Instance parent = {}); //!< \overload
/**
* Destroys this component from the given entity, children are orphaned.
* @param e An entity.
*
* @note If this transform had children, these are orphaned, which means their local
* transform becomes a world transform. Usually it's nonsensical. It's recommended to make
* sure that a destroyed transform doesn't have children.
*
* @see create()
*/
void destroy(utils::Entity e) noexcept;
/**
* Re-parents an entity to a new one.
* @param i The instance of the transform component to re-parent
* @param newParent The instance of the new parent transform
* @attention It is an error to re-parent an entity to a descendant and will cause undefined behaviour.
* @see getInstance()
*/
void setParent(Instance i, Instance newParent) noexcept;
/**
* Returns the parent of a transform component, or the null entity if it is a root.
* @param i The instance of the transform component to query.
*/
utils::Entity getParent(Instance i) const noexcept;
/**
* Returns the number of children of a transform component.
* @param i The instance of the transform component to query.
* @return The number of children of the queried component.
*/
size_t getChildCount(Instance i) const noexcept;
/**
* Gets a list of children for a transform component.
*
* @param i The instance of the transform component to query.
* @param children Pointer to array-of-Entity. The array must have at least "count" elements.
* @param count The maximum number of children to retrieve.
* @return The number of children written to the pointer.
*/
size_t getChildren(Instance i, utils::Entity* children, size_t count) const noexcept;
/**
* Returns an iterator to the Instance of the first child of the given parent.
*
* @param parent Instance of the parent
* @return A forward iterator pointing to the first child of the given parent.
*
* A child_iterator can only safely be dereferenced if it's different from getChildrenEnd(parent)
*/
children_iterator getChildrenBegin(Instance parent) const noexcept;
/**
* Returns an undreferencable iterator representing the end of the children list
*
* @param parent Instance of the parent
* @return A forward iterator.
*
* This iterator cannot be dereferenced
*/
children_iterator getChildrenEnd(Instance parent) const noexcept;
/**
* Sets a local transform of a transform component.
* @param ci The instance of the transform component to set the local transform to.
* @param localTransform The local transform (i.e. relative to the parent).
* @see getTransform()
* @attention This operation can be slow if the hierarchy of transform is too deep, and this
* will be particularly bad when updating a lot of transforms. In that case,
* consider using openLocalTransformTransaction() / commitLocalTransformTransaction().
*/
void setTransform(Instance ci, const math::mat4f& localTransform) noexcept;
/**
* Sets a local transform of a transform component and keeps double precision translation.
* All other values of the transform are stored at single precision.
* @param ci The instance of the transform component to set the local transform to.
* @param localTransform The local transform (i.e. relative to the parent).
* @see getTransform()
* @attention This operation can be slow if the hierarchy of transform is too deep, and this
* will be particularly bad when updating a lot of transforms. In that case,
* consider using openLocalTransformTransaction() / commitLocalTransformTransaction().
*/
void setTransform(Instance ci, const math::mat4& localTransform) noexcept;
/**
* Returns the local transform of a transform component.
* @param ci The instance of the transform component to query the local transform from.
* @return The local transform of the component (i.e. relative to the parent). This always
* returns the value set by setTransform().
* @see setTransform()
*/
const math::mat4f& getTransform(Instance ci) const noexcept;
/**
* Returns the local transform of a transform component.
* @param ci The instance of the transform component to query the local transform from.
* @return The local transform of the component (i.e. relative to the parent). This always
* returns the value set by setTransform().
* @see setTransform()
*/
const math::mat4 getTransformAccurate(Instance ci) const noexcept;
/**
* Return the world transform of a transform component.
* @param ci The instance of the transform component to query the world transform from.
* @return The world transform of the component (i.e. relative to the root). This is the
* composition of this component's local transform with its parent's world transform.
* @see setTransform()
*/
const math::mat4f& getWorldTransform(Instance ci) const noexcept;
/**
* Return the world transform of a transform component.
* @param ci The instance of the transform component to query the world transform from.
* @return The world transform of the component (i.e. relative to the root). This is the
* composition of this component's local transform with its parent's world transform.
* @see setTransform()
*/
const math::mat4 getWorldTransformAccurate(Instance ci) const noexcept;
/**
* Opens a local transform transaction. During a transaction, getWorldTransform() can
* return an invalid transform until commitLocalTransformTransaction() is called. However,
* setTransform() will perform significantly better and in constant time.
*
* This is useful when updating many transforms and the transform hierarchy is deep (say more
* than 4 or 5 levels).
*
* @note If the local transform transaction is already open, this is a no-op.
*
* @see commitLocalTransformTransaction(), setTransform()
*/
void openLocalTransformTransaction() noexcept;
/**
* Commits the currently open local transform transaction. When this returns, calls
* to getWorldTransform() will return the proper value.
*
* @attention failing to call this method when done updating the local transform will cause
* a lot of rendering problems. The system never closes the transaction
* automatically.
*
* @note If the local transform transaction is not open, this is a no-op.
*
* @see openLocalTransformTransaction(), setTransform()
*/
void commitLocalTransformTransaction() noexcept;
};
} // namespace filament
#endif // TNT_TRANSFORMMANAGER_H

201
ios/include/filament/VertexBuffer.h Normal file
View File

@@ -0,0 +1,201 @@
/*
* 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_VERTEXBUFFER_H
#define TNT_FILAMENT_VERTEXBUFFER_H
#include <filament/FilamentAPI.h>
#include <filament/MaterialEnums.h>
#include <backend/BufferDescriptor.h>
#include <backend/DriverEnums.h>
#include <utils/compiler.h>
namespace filament {
class FVertexBuffer;
class BufferObject;
class Engine;
/**
* Holds a set of buffers that define the geometry of a Renderable.
*
* The geometry of the Renderable itself is defined by a set of vertex attributes such as
* position, color, normals, tangents, etc...
*
* There is no need to have a 1-to-1 mapping between attributes and buffer. A buffer can hold the
* data of several attributes -- attributes are then referred as being "interleaved".
*
* The buffers themselves are GPU resources, therefore mutating their data can be relatively slow.
* For this reason, it is best to separate the constant data from the dynamic data into multiple
* buffers.
*
* It is possible, and even encouraged, to use a single vertex buffer for several Renderables.
*
* @see IndexBuffer, RenderableManager
*/
class UTILS_PUBLIC VertexBuffer : public FilamentAPI {
struct BuilderDetails;
public:
using AttributeType = backend::ElementType;
using BufferDescriptor = backend::BufferDescriptor;
class Builder : public BuilderBase<BuilderDetails> {
friend struct BuilderDetails;
public:
Builder() noexcept;
Builder(Builder const& rhs) noexcept;
Builder(Builder&& rhs) noexcept;
~Builder() noexcept;
Builder& operator=(Builder const& rhs) noexcept;
Builder& operator=(Builder&& rhs) noexcept;
/**
* Defines how many buffers will be created in this vertex buffer set. These buffers are
* later referenced by index from 0 to \p bufferCount - 1.
*
* This call is mandatory. The default is 0.
*
* @param bufferCount Number of buffers in this vertex buffer set. The maximum value is 8.
* @return A reference to this Builder for chaining calls.
*/
Builder& bufferCount(uint8_t bufferCount) noexcept;
/**
* Size of each buffer in the set in vertex.
*
* @param vertexCount Number of vertices in each buffer in this set.
* @return A reference to this Builder for chaining calls.
*/
Builder& vertexCount(uint32_t vertexCount) noexcept;
/**
* Allows buffers to be swapped out and shared using BufferObject.
*
* If buffer objects mode is enabled, clients must call setBufferObjectAt rather than
* setBufferAt. This allows sharing of data between VertexBuffer objects, but it may
* slightly increase the memory footprint of Filament's internal bookkeeping.
*
* @param enabled If true, enables buffer object mode. False by default.
*/
Builder& enableBufferObjects(bool enabled = true) noexcept;
/**
* Sets up an attribute for this vertex buffer set.
*
* Using \p byteOffset and \p byteStride, attributes can be interleaved in the same buffer.
*
* @param attribute The attribute to set up.
* @param bufferIndex The index of the buffer containing the data for this attribute. Must
* be between 0 and bufferCount() - 1.
* @param attributeType The type of the attribute data (e.g. byte, float3, etc...)
* @param byteOffset Offset in *bytes* into the buffer \p bufferIndex
* @param byteStride Stride in *bytes* to the next element of this attribute. When set to
* zero the attribute size, as defined by \p attributeType is used.
*
* @return A reference to this Builder for chaining calls.
*
* @warning VertexAttribute::TANGENTS must be specified as a quaternion and is how normals
* are specified.
*
* @warning Not all backends support 3-component attributes that are not floats. For help
* with conversion, see geometry::Transcoder.
*
* @see VertexAttribute
*
* This is a no-op if the \p attribute is an invalid enum.
* This is a no-op if the \p bufferIndex is out of bounds.
*
*/
Builder& attribute(VertexAttribute attribute, uint8_t bufferIndex,
AttributeType attributeType,
uint32_t byteOffset = 0, uint8_t byteStride = 0) noexcept;
/**
* Sets whether a given attribute should be normalized. By default attributes are not
* normalized. A normalized attribute is mapped between 0 and 1 in the shader. This applies
* only to integer types.
*
* @param attribute Enum of the attribute to set the normalization flag to.
* @param normalize true to automatically normalize the given attribute.
* @return A reference to this Builder for chaining calls.
*
* This is a no-op if the \p attribute is an invalid enum.
*/
Builder& normalized(VertexAttribute attribute, bool normalize = true) noexcept;
/**
* Creates the VertexBuffer object and returns a pointer to it.
*
* @param engine Reference to the filament::Engine to associate this VertexBuffer with.
*
* @return pointer to the newly created object or nullptr if exceptions are disabled and
* an error occurred.
*
* @exception utils::PostConditionPanic if a runtime error occurred, such as running out of
* memory or other resources.
* @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
*/
VertexBuffer* build(Engine& engine);
private:
friend class FVertexBuffer;
};
/**
* Returns the vertex count.
* @return Number of vertices in this vertex buffer set.
*/
size_t getVertexCount() const noexcept;
/**
* Asynchronously copy-initializes the specified buffer from the given buffer data.
*
* Do not use this if you called enableBufferObjects() on the Builder.
*
* @param engine Reference to the filament::Engine to associate this VertexBuffer with.
* @param bufferIndex Index of the buffer to initialize. Must be between 0
* and Builder::bufferCount() - 1.
* @param buffer A BufferDescriptor representing the data used to initialize the buffer at
* index \p bufferIndex. BufferDescriptor points to raw, untyped data that will
* be copied as-is into the buffer.
* @param byteOffset Offset in *bytes* into the buffer at index \p bufferIndex of this vertex
* buffer set.
*/
void setBufferAt(Engine& engine, uint8_t bufferIndex, BufferDescriptor&& buffer,
uint32_t byteOffset = 0);
/**
* Swaps in the given buffer object.
*
* To use this, you must first call enableBufferObjects() on the Builder.
*
* @param engine Reference to the filament::Engine to associate this VertexBuffer with.
* @param bufferIndex Index of the buffer to initialize. Must be between 0
* and Builder::bufferCount() - 1.
* @param bufferObject The handle to the GPU data that will be used in this buffer slot.
*/
void setBufferObjectAt(Engine& engine, uint8_t bufferIndex, BufferObject const* bufferObject);
};
} // namespace filament
#endif // TNT_FILAMENT_VERTEXBUFFER_H

911
ios/include/filament/View.h Normal file
View File

@@ -0,0 +1,911 @@
/*
* 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_VIEW_H
#define TNT_FILAMENT_VIEW_H
#include <filament/Color.h>
#include <filament/FilamentAPI.h>
#include <backend/DriverEnums.h>
#include <utils/compiler.h>
#include <math/mathfwd.h>
namespace filament {
class Camera;
class ColorGrading;
class MaterialInstance;
class RenderTarget;
class Scene;
class Texture;
class Viewport;
/**
* A View encompasses all the state needed for rendering a Scene.
*
* Renderer::render() operates on View objects. These View objects specify important parameters
* such as:
* - The Scene
* - The Camera
* - The Viewport
* - Some rendering parameters
*
* \note
* View instances are heavy objects that internally cache a lot of data needed for rendering.
* It is not advised for an application to use many View objects.
*
* For example, in a game, a View could be used for the main scene and another one for the
* game's user interface. More View instances could be used for creating special effects (e.g.
* a View is akin to a rendering pass).
*
*
* @see Renderer, Scene, Camera, RenderTarget
*/
class UTILS_PUBLIC View : public FilamentAPI {
public:
enum class QualityLevel : uint8_t {
LOW,
MEDIUM,
HIGH,
ULTRA
};
enum class BlendMode : uint8_t {
OPAQUE,
TRANSLUCENT
};
/**
* Dynamic resolution can be used to either reach a desired target frame rate
* by lowering the resolution of a View, or to increase the quality when the
* rendering is faster than the target frame rate.
*
* This structure can be used to specify the minimum scale factor used when
* lowering the resolution of a View, and the maximum scale factor used when
* increasing the resolution for higher quality rendering. The scale factors
* can be controlled on each X and Y axis independently. By default, all scale
* factors are set to 1.0.
*
* enabled: enable or disables dynamic resolution on a View
*
* homogeneousScaling: by default the system scales the major axis first. Set this to true
* to force homogeneous scaling.
*
* minScale: the minimum scale in X and Y this View should use
*
* maxScale: the maximum scale in X and Y this View should use
*
* quality: upscaling quality.
* LOW: 1 bilinear tap, Medium: 4 bilinear taps, High: 9 bilinear taps (tent)
*
* \note
* Dynamic resolution is only supported on platforms where the time to render
* a frame can be measured accurately. Dynamic resolution is currently only
* supported on Android.
*
* @see Renderer::FrameRateOptions
*
*/
struct DynamicResolutionOptions {
math::float2 minScale = math::float2(0.5f); //!< minimum scale factors in x and y
math::float2 maxScale = math::float2(1.0f); //!< maximum scale factors in x and y
bool enabled = false; //!< enable or disable dynamic resolution
bool homogeneousScaling = false; //!< set to true to force homogeneous scaling
QualityLevel quality = QualityLevel::LOW; //!< Upscaling quality
};
/**
* Options to control the bloom effect
*
* enabled: Enable or disable the bloom post-processing effect. Disabled by default.
*
* levels: Number of successive blurs to achieve the blur effect, the minimum is 3 and the
* maximum is 12. This value together with resolution influences the spread of the
* blur effect. This value can be silently reduced to accommodate the original
* image size.
*
* resolution: Resolution of bloom's minor axis. The minimum value is 2^levels and the
* the maximum is lower of the original resolution and 4096. This parameter is
* silently clamped to the minimum and maximum.
* It is highly recommended that this value be smaller than the target resolution
* after dynamic resolution is applied (horizontally and vertically).
*
* strength: how much of the bloom is added to the original image. Between 0 and 1.
*
* blendMode: Whether the bloom effect is purely additive (false) or mixed with the original
* image (true).
*
* anamorphism: Bloom's aspect ratio (x/y), for artistic purposes.
*
* threshold: When enabled, a threshold at 1.0 is applied on the source image, this is
* useful for artistic reasons and is usually needed when a dirt texture is used.
*
* dirt: A dirt/scratch/smudges texture (that can be RGB), which gets added to the
* bloom effect. Smudges are visible where bloom occurs. Threshold must be
* enabled for the dirt effect to work properly.
*
* dirtStrength: Strength of the dirt texture.
*/
struct BloomOptions {
enum class BlendMode : uint8_t {
ADD, //!< Bloom is modulated by the strength parameter and added to the scene
INTERPOLATE //!< Bloom is interpolated with the scene using the strength parameter
};
Texture* dirt = nullptr; //!< user provided dirt texture
float dirtStrength = 0.2f; //!< strength of the dirt texture
float strength = 0.10f; //!< bloom's strength between 0.0 and 1.0
uint32_t resolution = 360; //!< resolution of vertical axis (2^levels to 2048)
float anamorphism = 1.0f; //!< bloom x/y aspect-ratio (1/32 to 32)
uint8_t levels = 6; //!< number of blur levels (3 to 11)
BlendMode blendMode = BlendMode::ADD; //!< how the bloom effect is applied
bool threshold = true; //!< whether to threshold the source
bool enabled = false; //!< enable or disable bloom
float highlight = 1000.0f; //!< limit highlights to this value before bloom [10, +inf]
bool lensFlare = false; //!< enable screen-space lens flare
bool starburst = true; //!< enable starburst effect on lens flare
float chromaticAberration = 0.005f; //!< amount of chromatic aberration
uint8_t ghostCount = 4; //!< number of flare "ghosts"
float ghostSpacing = 0.6f; //!< spacing of the ghost in screen units [0, 1[
float ghostThreshold = 10.0f; //!< hdr threshold for the ghosts
float haloThickness = 0.1f; //!< thickness of halo in vertical screen units, 0 to disable
float haloRadius = 0.4f; //!< radius of halo in vertical screen units [0, 0.5]
float haloThreshold = 10.0f; //!< hdr threshold for the halo
};
/**
* Options to control fog in the scene
*/
struct FogOptions {
float distance = 0.0f; //!< distance in world units from the camera where the fog starts ( >= 0.0 )
float maximumOpacity = 1.0f; //!< fog's maximum opacity between 0 and 1
float height = 0.0f; //!< fog's floor in world units
float heightFalloff = 1.0f; //!< how fast fog dissipates with altitude
LinearColor color{0.5f}; //!< fog's color (linear), see fogColorFromIbl
float density = 0.1f; //!< fog's density at altitude given by 'height'
float inScatteringStart = 0.0f; //!< distance in world units from the camera where in-scattering starts
float inScatteringSize = -1.0f; //!< size of in-scattering (>0 to activate). Good values are >> 1 (e.g. ~10 - 100).
bool fogColorFromIbl = false; //!< Fog color will be modulated by the IBL color in the view direction.
bool enabled = false; //!< enable or disable fog
};
/**
* Options to control Depth of Field (DoF) effect in the scene.
*
* cocScale can be used to set the depth of field blur independently from the camera
* aperture, e.g. for artistic reasons. This can be achieved by setting:
* cocScale = cameraAperture / desiredDoFAperture
*
* @see Camera
*/
struct DepthOfFieldOptions {
enum class Filter : uint8_t {
NONE = 0,
MEDIAN = 2
};
float cocScale = 1.0f; //!< circle of confusion scale factor (amount of blur)
float maxApertureDiameter = 0.01f; //!< maximum aperture diameter in meters (zero to disable rotation)
bool enabled = false; //!< enable or disable depth of field effect
Filter filter = Filter::MEDIAN; //!< filter to use for filling gaps in the kernel
bool nativeResolution = false; //!< perform DoF processing at native resolution
/**
* Number of of rings used by the gather kernels. The number of rings affects quality
* and performance. The actual number of sample per pixel is defined
* as (ringCount * 2 - 1)^2. Here are a few commonly used values:
* 3 rings : 25 ( 5x 5 grid)
* 4 rings : 49 ( 7x 7 grid)
* 5 rings : 81 ( 9x 9 grid)
* 17 rings : 1089 (33x33 grid)
*
* With a maximum circle-of-confusion of 32, it is never necessary to use more than 17 rings.
*
* Usually all three settings below are set to the same value, however, it is often
* acceptable to use a lower ring count for the "fast tiles", which improves performance.
* Fast tiles are regions of the screen where every pixels have a similar
* circle-of-confusion radius.
*
* A value of 0 means default, which is 5 on desktop and 3 on mobile.
*
* @{
*/
uint8_t foregroundRingCount = 0; //!< number of kernel rings for foreground tiles
uint8_t backgroundRingCount = 0; //!< number of kernel rings for background tiles
uint8_t fastGatherRingCount = 0; //!< number of kernel rings for fast tiles
/** @}*/
/**
* maximum circle-of-confusion in pixels for the foreground, must be in [0, 32] range.
* A value of 0 means default, which is 32 on desktop and 24 on mobile.
*/
uint16_t maxForegroundCOC = 0;
/**
* maximum circle-of-confusion in pixels for the background, must be in [0, 32] range.
* A value of 0 means default, which is 32 on desktop and 24 on mobile.
*/
uint16_t maxBackgroundCOC = 0;
};
/**
* Options to control the vignetting effect.
*/
struct VignetteOptions {
float midPoint = 0.5f; //!< high values restrict the vignette closer to the corners, between 0 and 1
float roundness = 0.5f; //!< controls the shape of the vignette, from a rounded rectangle (0.0), to an oval (0.5), to a circle (1.0)
float feather = 0.5f; //!< softening amount of the vignette effect, between 0 and 1
LinearColorA color{0.0f, 0.0f, 0.0f, 1.0f}; //!< color of the vignette effect, alpha is currently ignored
bool enabled = false; //!< enables or disables the vignette effect
};
/**
* Structure used to set the precision of the color buffer and related quality settings.
*
* @see setRenderQuality, getRenderQuality
*/
struct RenderQuality {
/**
* Sets the quality of the HDR color buffer.
*
* A quality of HIGH or ULTRA means using an RGB16F or RGBA16F color buffer. This means
* colors in the LDR range (0..1) have a 10 bit precision. A quality of LOW or MEDIUM means
* using an R11G11B10F opaque color buffer or an RGBA16F transparent color buffer. With
* R11G11B10F colors in the LDR range have a precision of either 6 bits (red and green
* channels) or 5 bits (blue channel).
*/
QualityLevel hdrColorBuffer = QualityLevel::HIGH;
};
/**
* Options for screen space Ambient Occlusion (SSAO) and Screen Space Cone Tracing (SSCT)
* @see setAmbientOcclusionOptions()
*/
struct AmbientOcclusionOptions {
float radius = 0.3f; //!< Ambient Occlusion radius in meters, between 0 and ~10.
float power = 1.0f; //!< Controls ambient occlusion's contrast. Must be positive.
float bias = 0.0005f; //!< Self-occlusion bias in meters. Use to avoid self-occlusion. Between 0 and a few mm.
float resolution = 0.5f;//!< How each dimension of the AO buffer is scaled. Must be either 0.5 or 1.0.
float intensity = 1.0f; //!< Strength of the Ambient Occlusion effect.
float bilateralThreshold = 0.05f; //!< depth distance that constitute an edge for filtering
QualityLevel quality = QualityLevel::LOW; //!< affects # of samples used for AO.
QualityLevel lowPassFilter = QualityLevel::MEDIUM; //!< affects AO smoothness
QualityLevel upsampling = QualityLevel::LOW; //!< affects AO buffer upsampling quality
bool enabled = false; //!< enables or disables screen-space ambient occlusion
bool bentNormals = false; //!< enables bent normals computation from AO, and specular AO
float minHorizonAngleRad = 0.0f; //!< min angle in radian to consider
/**
* Screen Space Cone Tracing (SSCT) options
* Ambient shadows from dominant light
*/
struct Ssct {
float lightConeRad = 1.0f; //!< full cone angle in radian, between 0 and pi/2
float shadowDistance = 0.3f; //!< how far shadows can be cast
float contactDistanceMax = 1.0f; //!< max distance for contact
float intensity = 0.8f; //!< intensity
math::float3 lightDirection{ 0, -1, 0 }; //!< light direction
float depthBias = 0.01f; //!< depth bias in world units (mitigate self shadowing)
float depthSlopeBias = 0.01f; //!< depth slope bias (mitigate self shadowing)
uint8_t sampleCount = 4; //!< tracing sample count, between 1 and 255
uint8_t rayCount = 1; //!< # of rays to trace, between 1 and 255
bool enabled = false; //!< enables or disables SSCT
} ssct;
};
/**
* Options for Temporal Anti-aliasing (TAA)
* @see setTemporalAntiAliasingOptions()
*/
struct TemporalAntiAliasingOptions {
float filterWidth = 1.0f; //!< reconstruction filter width typically between 0 (sharper, aliased) and 1 (smoother)
float feedback = 0.04f; //!< history feedback, between 0 (maximum temporal AA) and 1 (no temporal AA).
bool enabled = false; //!< enables or disables temporal anti-aliasing
};
/**
* List of available post-processing anti-aliasing techniques.
* @see setAntiAliasing, getAntiAliasing, setSampleCount
*/
enum class AntiAliasing : uint8_t {
NONE = 0, //!< no anti aliasing performed as part of post-processing
FXAA = 1 //!< FXAA is a low-quality but very efficient type of anti-aliasing. (default).
};
/**
* List of available post-processing dithering techniques.
*/
enum class Dithering : uint8_t {
NONE = 0, //!< No dithering
TEMPORAL = 1 //!< Temporal dithering (default)
};
/**
* List of available shadow mapping techniques.
* @see setShadowType
*/
enum class ShadowType : uint8_t {
PCF, //!< percentage-closer filtered shadows (default)
VSM //!< variance shadows
};
/**
* View-level options for VSM Shadowing.
* @see setVsmShadowOptions()
* @warning This API is still experimental and subject to change.
*/
struct VsmShadowOptions {
/**
* Sets the number of anisotropic samples to use when sampling a VSM shadow map. If greater
* than 0, mipmaps will automatically be generated each frame for all lights.
*
* The number of anisotropic samples = 2 ^ vsmAnisotropy.
*/
uint8_t anisotropy = 0;
/**
* Whether to generate mipmaps for all VSM shadow maps.
*/
bool mipmapping = false;
/**
* EVSM exponent.
* The maximum value permissible is 5.54 for a shadow map in fp16, or 42.0 for a
* shadow map in fp32. Currently the shadow map bit depth is always fp16.
*/
float exponent = 5.54f;
/**
* VSM minimum variance scale, must be positive.
*/
float minVarianceScale = 0.5f;
/**
* VSM light bleeding reduction amount, between 0 and 1.
*/
float lightBleedReduction = 0.15f;
};
/**
* Sets the View's name. Only useful for debugging.
* @param name Pointer to the View's name. The string is copied.
*/
void setName(const char* name) noexcept;
/**
* Returns the View's name
*
* @return a pointer owned by the View instance to the View's name.
*
* @attention Do *not* free the pointer or modify its content.
*/
const char* getName() const noexcept;
/**
* Set this View instance's Scene.
*
* @param scene Associate the specified Scene to this View. A Scene can be associated to
* several View instances.\n
* \p scene can be nullptr to dissociate the currently set Scene
* from this View.\n
* The View doesn't take ownership of the Scene pointer (which
* acts as a reference).
*
* @note
* There is no reference-counting.
* Make sure to dissociate a Scene from all Views before destroying it.
*/
void setScene(Scene* scene);
/**
* Returns the Scene currently associated with this View.
* @return A pointer to the Scene associated to this View. nullptr if no Scene is set.
*/
Scene* getScene() noexcept;
/**
* Returns the Scene currently associated with this View.
* @return A pointer to the Scene associated to this View. nullptr if no Scene is set.
*/
Scene const* getScene() const noexcept {
return const_cast<View*>(this)->getScene();
}
/**
* Specifies an offscreen render target to render into.
*
* By default, the view's associated render target is nullptr, which corresponds to the
* SwapChain associated with the engine.
*
* A view with a custom render target cannot rely on Renderer::ClearOptions, which only apply
* to the SwapChain. Such view can use a Skybox instead.
*
* @param renderTarget Render target associated with view, or nullptr for the swap chain.
*/
void setRenderTarget(RenderTarget* renderTarget) noexcept;
/**
* Gets the offscreen render target associated with this view.
*
* Returns nullptr if the render target is the swap chain (which is default).
*
* @see setRenderTarget
*/
RenderTarget* getRenderTarget() const noexcept;
/**
* Sets the rectangular region to render to.
*
* The viewport specifies where the content of the View (i.e. the Scene) is rendered in
* the render target. The Render target is automatically clipped to the Viewport.
*
* @param viewport The Viewport to render the Scene into. The Viewport is a value-type, it is
* therefore copied. The parameter can be discarded after this call returns.
*/
void setViewport(Viewport const& viewport) noexcept;
/**
* Returns the rectangular region that gets rendered to.
* @return A constant reference to View's viewport.
*/
Viewport const& getViewport() const noexcept;
/**
* Sets this View's Camera.
*
* @param camera Associate the specified Camera to this View. A Camera can be associated to
* several View instances.\n
* \p camera can be nullptr to dissociate the currently set Camera from this
* View.\n
* The View doesn't take ownership of the Camera pointer (which
* acts as a reference).
*
* @note
* There is no reference-counting.
* Make sure to dissociate a Camera from all Views before destroying it.
*/
void setCamera(Camera* camera) noexcept;
/**
* Returns the Camera currently associated with this View.
* @return A reference to the Camera associated to this View.
*/
Camera& getCamera() noexcept;
/**
* Returns the Camera currently associated with this View.
* @return A reference to the Camera associated to this View.
*/
Camera const& getCamera() const noexcept {
return const_cast<View*>(this)->getCamera();
}
/**
* Sets the blending mode used to draw the view into the SwapChain.
*
* @param blendMode either BlendMode::OPAQUE or BlendMode::TRANSLUCENT
* @see getBlendMode
*/
void setBlendMode(BlendMode blendMode) noexcept;
/**
*
* @return blending mode set by setBlendMode
* @see setBlendMode
*/
BlendMode getBlendMode() const noexcept;
/**
* Sets which layers are visible.
*
* Renderable objects can have one or several layers associated to them. Layers are
* represented with an 8-bits bitmask, where each bit corresponds to a layer.
* @see RenderableManager::setLayerMask().
*
* This call sets which of those layers are visible. Renderables in invisible layers won't be
* rendered.
*
* @param select a bitmask specifying which layer to set or clear using \p values.
* @param values a bitmask where each bit sets the visibility of the corresponding layer
* (1: visible, 0: invisible), only layers in \p select are affected.
*
* @note By default all layers are visible.
* @note This is a convenient way to quickly show or hide sets of Renderable objects.
*/
void setVisibleLayers(uint8_t select, uint8_t values) noexcept;
/**
* Get the visible layers.
*
* @see View::setVisibleLayers()
*/
uint8_t getVisibleLayers() const noexcept;
/**
* Enables or disables shadow mapping. Enabled by default.
*
* @param enabled true enables shadow mapping, false disables it.
*
* @see LightManager::Builder::castShadows(),
* RenderableManager::Builder::receiveShadows(),
* RenderableManager::Builder::castShadows(),
*/
void setShadowingEnabled(bool enabled) noexcept;
/**
* @return whether shadowing is enabled
*/
bool isShadowingEnabled() const noexcept;
/**
* Enables or disables screen space refraction. Enabled by default.
*
* @param enabled true enables screen space refraction, false disables it.
*/
void setScreenSpaceRefractionEnabled(bool enabled) noexcept;
/**
* @return whether screen space refraction is enabled
*/
bool isScreenSpaceRefractionEnabled() const noexcept;
/**
* Sets how many samples are to be used for MSAA in the post-process stage.
* Default is 1 and disables MSAA.
*
* @param count number of samples to use for multi-sampled anti-aliasing.\n
* 0: treated as 1
* 1: no anti-aliasing
* n: sample count. Effective sample could be different depending on the
* GPU capabilities.
*
* @note Anti-aliasing can also be performed in the post-processing stage, generally at lower
* cost. See setAntialiasing.
*
* @see setAntialiasing
*/
void setSampleCount(uint8_t count = 1) noexcept;
/**
* Returns the sample count set by setSampleCount(). Effective sample count could be different.
* A value of 0 or 1 means MSAA is disabled.
*
* @return value set by setSampleCount().
*/
uint8_t getSampleCount() const noexcept;
/**
* Enables or disables anti-aliasing in the post-processing stage. Enabled by default.
* MSAA can be enabled in addition, see setSampleCount().
*
* @param type FXAA for enabling, NONE for disabling anti-aliasing.
*
* @note For MSAA anti-aliasing, see setSamplerCount().
*
* @see setSampleCount
*/
void setAntiAliasing(AntiAliasing type) noexcept;
/**
* Queries whether anti-aliasing is enabled during the post-processing stage. To query
* whether MSAA is enabled, see getSampleCount().
*
* @return The post-processing anti-aliasing method.
*/
AntiAliasing getAntiAliasing() const noexcept;
/**
* Enables or disable temporal anti-aliasing (TAA). Disabled by default.
*
* @param options temporal anti-aliasing options
*/
void setTemporalAntiAliasingOptions(TemporalAntiAliasingOptions options) noexcept;
/**
* Returns temporal anti-aliasing options.
*
* @return temporal anti-aliasing options
*/
TemporalAntiAliasingOptions const& getTemporalAntiAliasingOptions() const noexcept;
/**
* Sets this View's color grading transforms.
*
* @param colorGrading Associate the specified ColorGrading to this View. A ColorGrading can be
* associated to several View instances.\n
* \p colorGrading can be nullptr to dissociate the currently set
* ColorGrading from this View. Doing so will revert to the use of the
* default color grading transforms.\n
* The View doesn't take ownership of the ColorGrading pointer (which
* acts as a reference).
*
* @note
* There is no reference-counting.
* Make sure to dissociate a ColorGrading from all Views before destroying it.
*/
void setColorGrading(ColorGrading* colorGrading) noexcept;
/**
* Returns the color grading transforms currently associated to this view.
* @return A pointer to the ColorGrading associated to this View.
*/
const ColorGrading* getColorGrading() const noexcept;
/**
* Sets ambient occlusion options.
*
* @param options Options for ambient occlusion.
*/
void setAmbientOcclusionOptions(AmbientOcclusionOptions const& options) noexcept;
/**
* Gets the ambient occlusion options.
*
* @return ambient occlusion options currently set.
*/
AmbientOcclusionOptions const& getAmbientOcclusionOptions() const noexcept;
/**
* Enables or disables bloom in the post-processing stage. Disabled by default.
*
* @param options options
*/
void setBloomOptions(BloomOptions options) noexcept;
/**
* Queries the bloom options.
*
* @return the current bloom options for this view.
*/
BloomOptions getBloomOptions() const noexcept;
/**
* Enables or disables fog. Disabled by default.
*
* @param options options
*/
void setFogOptions(FogOptions options) noexcept;
/**
* Queries the fog options.
*
* @return the current fog options for this view.
*/
FogOptions getFogOptions() const noexcept;
/**
* Enables or disables Depth of Field. Disabled by default.
*
* @param options options
*/
void setDepthOfFieldOptions(DepthOfFieldOptions options) noexcept;
/**
* Queries the depth of field options.
*
* @return the current depth of field options for this view.
*/
DepthOfFieldOptions getDepthOfFieldOptions() const noexcept;
/**
* Enables or disables the vignetted effect in the post-processing stage. Disabled by default.
*
* @param options options
*/
void setVignetteOptions(VignetteOptions options) noexcept;
/**
* Queries the vignette options.
*
* @return the current vignette options for this view.
*/
VignetteOptions getVignetteOptions() const noexcept;
/**
* Enables or disables dithering in the post-processing stage. Enabled by default.
*
* @param dithering dithering type
*/
void setDithering(Dithering dithering) noexcept;
/**
* Queries whether dithering is enabled during the post-processing stage.
*
* @return the current dithering type for this view.
*/
Dithering getDithering() const noexcept;
/**
* Sets the dynamic resolution options for this view. Dynamic resolution options
* controls whether dynamic resolution is enabled, and if it is, how it behaves.
*
* @param options The dynamic resolution options to use on this view
*/
void setDynamicResolutionOptions(DynamicResolutionOptions const& options) noexcept;
/**
* Returns the dynamic resolution options associated with this view.
* @return value set by setDynamicResolutionOptions().
*/
DynamicResolutionOptions getDynamicResolutionOptions() const noexcept;
/**
* Sets the rendering quality for this view. Refer to RenderQuality for more
* information about the different settings available.
*
* @param renderQuality The render quality to use on this view
*/
void setRenderQuality(RenderQuality const& renderQuality) noexcept;
/**
* Returns the render quality used by this view.
* @return value set by setRenderQuality().
*/
RenderQuality getRenderQuality() const noexcept;
/**
* Sets options relative to dynamic lighting for this view.
*
* @param zLightNear Distance from the camera where the lights are expected to shine.
* This parameter can affect performance and is useful because depending
* on the scene, lights that shine close to the camera may not be
* visible -- in this case, using a larger value can improve performance.
* e.g. when standing and looking straight, several meters of the ground
* isn't visible and if lights are expected to shine there, there is no
* point using a short zLightNear. (Default 5m).
*
* @param zLightFar Distance from the camera after which lights are not expected to be visible.
* Similarly to zLightNear, setting this value properly can improve
* performance. (Default 100m).
*
*
* Together zLightNear and zLightFar must be chosen so that the visible influence of lights
* is spread between these two values.
*
*/
void setDynamicLightingOptions(float zLightNear, float zLightFar) noexcept;
/*
* Set the shadow mapping technique this View uses.
*
* The ShadowType affects all the shadows seen within the View.
*
* ShadowType::VSM imposes a restriction on marking renderables as only shadow receivers (but
* not casters). To ensure correct shadowing with VSM, all shadow participant renderables should
* be marked as both receivers and casters. Objects that are guaranteed to not cast shadows on
* themselves or other objects (such as flat ground planes) can be set to not cast shadows,
* which might improve shadow quality.
*
* @warning This API is still experimental and subject to change.
*/
void setShadowType(ShadowType shadow) noexcept;
/**
* Sets VSM shadowing options that apply across the entire View.
*
* Additional light-specific VSM options can be set with LightManager::setShadowOptions.
*
* Only applicable when shadow type is set to ShadowType::VSM.
*
* @param options Options for shadowing.
*
* @see setShadowType
*
* @warning This API is still experimental and subject to change.
*/
void setVsmShadowOptions(VsmShadowOptions const& options) noexcept;
/**
* Returns the VSM shadowing options associated with this View.
*
* @return value set by setVsmShadowOptions().
*/
VsmShadowOptions getVsmShadowOptions() const noexcept;
/**
* Enables or disables post processing. Enabled by default.
*
* Post-processing includes:
* - Bloom
* - Tone-mapping & gamma encoding
* - Dithering
* - MSAA
* - FXAA
* - Dynamic scaling
*
* Disabling post-processing forgoes color correctness as well as anti-aliasing and
* should only be used experimentally (e.g., for UI overlays).
*
* @param enabled true enables post processing, false disables it.
*
* @see setBloomOptions, setColorGrading, setAntiAliasing, setDithering, setSampleCount
*/
void setPostProcessingEnabled(bool enabled) noexcept;
//! Returns true if post-processing is enabled. See setPostProcessingEnabled() for more info.
bool isPostProcessingEnabled() const noexcept;
/**
* Inverts the winding order of front faces. By default front faces use a counter-clockwise
* winding order. When the winding order is inverted, front faces are faces with a clockwise
* winding order.
*
* Changing the winding order will directly affect the culling mode in materials
* (see Material::getCullingMode()).
*
* Inverting the winding order of front faces is useful when rendering mirrored reflections
* (water, mirror surfaces, front camera in AR, etc.).
*
* @param inverted True to invert front faces, false otherwise.
*/
void setFrontFaceWindingInverted(bool inverted) noexcept;
/**
* Returns true if the winding order of front faces is inverted.
* See setFrontFaceWindingInverted() for more information.
*/
bool isFrontFaceWindingInverted() const noexcept;
// for debugging...
//! debugging: allows to entirely disable frustum culling. (culling enabled by default).
void setFrustumCullingEnabled(bool culling) noexcept;
//! debugging: returns whether frustum culling is enabled.
bool isFrustumCullingEnabled() const noexcept;
//! debugging: sets the Camera used for rendering. It may be different from the culling camera.
void setDebugCamera(Camera* camera) noexcept;
//! debugging: returns a Camera from the point of view of *the* dominant directional light used for shadowing.
Camera const* getDirectionalLightCamera() const noexcept;
/**
* List of available ambient occlusion techniques
* @deprecated use AmbientOcclusionOptions::enabled instead
*/
enum class UTILS_DEPRECATED AmbientOcclusion : uint8_t {
NONE = 0, //!< No Ambient Occlusion
SSAO = 1 //!< Basic, sampling SSAO
};
/**
* Activates or deactivates ambient occlusion.
* @deprecated use setAmbientOcclusionOptions() instead
* @see setAmbientOcclusionOptions
*
* @param ambientOcclusion Type of ambient occlusion to use.
*/
UTILS_DEPRECATED
void setAmbientOcclusion(AmbientOcclusion ambientOcclusion) noexcept;
/**
* Queries the type of ambient occlusion active for this View.
* @deprecated use getAmbientOcclusionOptions() instead
* @see getAmbientOcclusionOptions
*
* @return ambient occlusion type.
*/
UTILS_DEPRECATED
AmbientOcclusion getAmbientOcclusion() const noexcept;
};
} // namespace filament
#endif // TNT_FILAMENT_VIEW_H

105
ios/include/filament/Viewport.h Normal file
View File

@@ -0,0 +1,105 @@
/*
* 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_VIEWPORT_H
#define TNT_FILAMENT_VIEWPORT_H
#include <backend/DriverEnums.h>
#include <utils/compiler.h>
#include <math/scalar.h>
#include <math/mathfwd.h>
#include <stddef.h>
#include <stdint.h>
namespace filament {
/**
* Viewport describes a view port in pixel coordinates
*
* A view port is represented by its left-bottom coordinate, width and height in pixels.
*/
class UTILS_PUBLIC Viewport : public backend::Viewport {
public:
/**
* Creates a Viewport of zero width and height at the origin.
*/
Viewport() noexcept : backend::Viewport{} {}
Viewport(const Viewport& viewport) noexcept = default;
Viewport(Viewport&& viewport) noexcept = default;
Viewport& operator=(const Viewport& viewport) noexcept = default;
Viewport& operator=(Viewport&& viewport) noexcept = default;
/**
* Creates a Viewport from its left-bottom coordinates, width and height in pixels
*
* @param left left coordinate in pixel
* @param bottom bottom coordinate in pixel
* @param width width in pixel
* @param height height in pixel
*/
Viewport(int32_t left, int32_t bottom, uint32_t width, uint32_t height) noexcept
: backend::Viewport{ left, bottom, width, height } {
}
/**
* Returns whether the area of the view port is null.
*
* @return true if either width or height is 0 pixel.
*/
bool empty() const noexcept { return !width || !height; }
/**
* Computes a new scaled Viewport
* @param s scaling factor on the x and y axes.
* @return A new scaled Viewport. The coordinates and dimensions of the new Viewport are
* rounded to the nearest integer value.
*/
Viewport scale(math::float2 s) const noexcept;
private:
/**
* Compares two Viewports for equality
* @param lhs reference to the left hand side Viewport
* @param rhs reference to the right hand side Viewport
* @return true if \p rhs and \p lhs are identical.
*/
friend bool operator==(Viewport const& lhs, Viewport const& rhs) noexcept {
return (&rhs == &lhs) ||
(rhs.left == lhs.left && rhs.bottom == lhs.bottom &&
rhs.width == lhs.width && rhs.height == lhs.height);
}
/**
* Compares two Viewports for inequality
* @param lhs reference to the left hand side Viewport
* @param rhs reference to the right hand side Viewport
* @return true if \p rhs and \p lhs are different.
*/
friend bool operator!=(Viewport const& lhs, Viewport const& rhs) noexcept {
return !(rhs == lhs);
}
};
} // namespace filament
#endif // TNT_FILAMENT_VIEWPORT_H