Merge branch 'devel' of gitlab.com:embree/embree into devel

Author: svenwoop

CHANGELOG.md

@@ -1,6 +1,36 @@
 Version History
 ---------------
 
+### New Features in Embree 3.0.0
+-   Switched to a new version of the API which provides improved
+    flexibility but is not backwards compatible. Please see "Upgrading
+    from Embree 2 to Embree 3" section of documentation for upgrade
+    instructions. In particular, we provide a python script that performs
+    most of the transition work.
+-   User geometries inside an instanced scene and a top-level scene no
+    longer need to handle instID field of ray differently. They both
+    just need to copy the context.instID into the ray.instID field.
+-   Support for context filter functions that can get assigned to a ray
+    query.
+-   User geometries can now invoke filter functions using the
+    rtcFilterIntersection and rtcFilterOcclusion calls.
+-   Higher flexibility through specifying build quality per scene and
+    geometry.
+-   Geometry normal uses commonly used right hand rule from now on.
+-   Added self intersection avoidance to ribbon curves and
+    lines. Applications do not have to implement self intersections workarounds
+    for these primitive types anymore.
+-   Added support for 4 billion primitives in a single scene.
+-   Removed RTC_MAX_USER_VERTEX_BUFFERS and RTC_MAX_INDEX_BUFFERS
+    limitation.
+-   Reduced memory consumption by 192 bytes per instance.
+-   Individual Contributor License Agreement (ICLA) and Corporate
+    Contributor License Agreement (CCLA) no longer required to
+    contribute to the project.
+
+### New Features in Embree 2.17.2
+-   Made BVH build of curve geometry deterministic.
+
 ### New Features in Embree 2.17.1
 -   Improved performance of occlusion ray packets by up to 50%.
 -   Fixed detection of Clang for CMake 3 under MacOSX

README.md

@@ -3,7 +3,7 @@
 .IP
 .nf
 \f[C]
-RTCHit\ \-\ type\ of\ single\ hit
+RTCHit\ \-\ single\ hit\ structure
 \f[]
 .fi
 .SS SYNOPSIS
@@ -14,37 +14,38 @@ RTCHit\ \-\ type\ of\ single\ hit
 
 struct\ RTCHit
 {
-\ \ float\ Ng_x;\ \ \ \ \ \ \ \ //!<\ x\ coordinate\ of\ geometry\ normal
-\ \ float\ Ng_y;\ \ \ \ \ \ \ \ //!<\ y\ coordinate\ of\ geometry\ normal
-\ \ float\ Ng_z;\ \ \ \ \ \ \ \ //!<\ z\ coordinate\ of\ geometry\ normal
+\ \ float\ Ng_x;\ \ \ \ \ \ \ \ \ \ //\ x\ coordinate\ of\ geometry\ normal
+\ \ float\ Ng_y;\ \ \ \ \ \ \ \ \ \ //\ y\ coordinate\ of\ geometry\ normal
+\ \ float\ Ng_z;\ \ \ \ \ \ \ \ \ \ //\ z\ coordinate\ of\ geometry\ normal
 
-\ \ float\ t;\ \ \ \ \ \ \ \ \ \ //!<\ hit\ distance
-\ \ float\ u;\ \ \ \ \ \ \ \ \ \ //!<\ Barycentric\ u\ coordinate\ of\ hit
-\ \ float\ v;\ \ \ \ \ \ \ \ \ \ //!<\ Barycentric\ v\ coordinate\ of\ hit
+\ \ float\ u;\ \ \ \ \ \ \ \ \ \ \ \ \ //\ barycentric\ u\ coordinate\ of\ hit
+\ \ float\ v;\ \ \ \ \ \ \ \ \ \ \ \ \ //\ barycentric\ v\ coordinate\ of\ hit
 
-\ \ unsigned\ primID;\ \ //!<\ primitive\ ID
-\ \ unsigned\ geomID;\ \ //!<\ geometry\ ID
-\ \ unsigned\ instID;\ \ //!<\ instance\ ID
+\ \ unsigned\ int\ primID;\ //\ geometry\ ID
+\ \ unsigned\ int\ geomID;\ //\ primitive\ ID
+\ \ unsigned\ int\ instID[RTC_MAX_INSTANCE_LEVEL_COUNT];\ //\ instance\ ID
 };
 \f[]
 .fi
 .SS DESCRIPTION
 .PP
 The \f[C]RTCHit\f[] type defines the type of a ray/primitive
-intersection result as passed to some callback functions.
+intersection result.
 The hit contains the unnormalized geometric normal in object space at
 the hit location (\f[C]Ng_x\f[], \f[C]Ng_y\f[], \f[C]Ng_z\f[] members),
-the parametric hit distance (\f[C]t\f[] member), the barycentric u/v
-coordinates of the hit (\f[C]u\f[] and \f[C]v\f[] members), as well as
-the primitive, geometry, and instance ID of the hit (\f[C]primID\f[],
-\f[C]geomID\f[], and \f[C]instID\f[] member).
+the barycentric u/v coordinates of the hit (\f[C]u\f[] and \f[C]v\f[]
+members), as well as the primitive ID (\f[C]primID\f[] member), geometry
+ID (\f[C]geomID\f[] member), and instance ID (\f[C]instID\f[] member) of
+the hit.
+The parametric intersection distance is not stored inside the hit, but
+stored inside the \f[C]tfar\f[] member of the ray.
 .PP
 The \f[C]embree3/rtcore_ray.h\f[] header additionally defines the same
-hit structure in structure of array layout (SOA) for hit packets of size
+hit structure in structure of array (SOA) layout for hit packets of size
 4 (\f[C]RTCHit4\f[] type), size 8 (\f[C]RTCHit8\f[] type), and size 16
 (\f[C]RTCHit16\f[] type).
-The header additionally defines an \f[C]RTCHitNt\f[] template to
-generate hit packets of an arbitrary compile time size.
+The header additionally defines an \f[C]RTCHitNt\f[] template for hit
+packets of an arbitrary compile\-time size.
 .SS EXIT STATUS
 .SS SEE ALSO
 .PP

man/man3/RTCHit.3embree3

@@ -14,38 +14,36 @@ RTCHitN\ \-\ hit\ packet\ of\ runtime\ size
 
 struct\ HitN;
 
-float&\ RTCHitN_Ng_x(RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
-float&\ RTCHitN_Ng_y(RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
-float&\ RTCHitN_Ng_z(RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
+float&\ RTCHitN_Ng_x(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCHitN_Ng_y(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCHitN_Ng_z(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i);
 
-unsigned&\ RTCHitN_primID(RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
-unsigned&\ RTCHitN_geomID(RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
-unsigned&\ RTCHitN_instID(RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
+float&\ RTCHitN_u(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCHitN_v(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i);
 
-float&\ RTCHitN_u\ \ \ (RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
-float&\ RTCHitN_v\ \ \ (RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
-float&\ RTCHitN_t\ \ \ (RTCHitN*\ hits,\ size_t\ N,\ size_t\ i);
+unsigned&\ RTCHitN_primID(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i);
+unsigned&\ RTCHitN_geomID(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i);
+unsigned&\ RTCHitN_instID(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i,\ unsigned\ int\ l);
 \f[]
 .fi
 .SS DESCRIPTION
 .PP
 When the hit packet size is not known at compile time (e.g.
-when Embree returns a potential hit packet in the
-\f[C]RTCFilterFuncN\f[] callback function), Embree uses the
-\f[C]RTCHitN\f[] type for hit packets.
-These hit packets can only have size 1, 4, 8, or 16, no other packet
-size will get used.
+when Embree returns a hit packet in the \f[C]RTCFilterFuncN\f[] callback
+function), Embree uses the \f[C]RTCHitN\f[] type for hit packets.
+These hit packets can only have sizes of 1, 4, 8, or 16.
+No other packet size will be used.
 .PP
 You can either implement different special code paths for each of these
-possible packet sizes and cast the hit to the appropiate hit packet
+possible packet sizes and cast the hit to the appropriate hit packet
 type, or implement one general code path that uses the
-\f[C]RTCHit_XXX\f[] helper functions to access hit packet components.
+\f[C]RTCHitN_XXX\f[] helper functions to access hit packet components.
 .PP
-These helper functions get a pointer to the hit packet (\f[C]ptr\f[]
+These helper functions get a pointer to the hit packet (\f[C]hit\f[]
 argument), the packet size (\f[C]N\f[] argument), and returns a
-reference to some component (e.g.
-x\-component of Ng) of the the ith hit of the packet (\f[C]i\f[]
-argument).
+reference to a component (e.g.
+x component of \f[C]Ng\f[]) of the the i\-th hit of the packet
+(\f[C]i\f[] argument).
 .SS EXIT STATUS
 .SS SEE ALSO
 .PP

man/man3/RTCHitN.3embree3

@@ -3,7 +3,7 @@
 .IP
 .nf
 \f[C]
-RTCRay\ \-\ type\ of\ single\ ray
+RTCRay\ \-\ single\ ray\ structure
 \f[]
 .fi
 .SS SYNOPSIS
@@ -12,35 +12,22 @@ RTCRay\ \-\ type\ of\ single\ ray
 \f[C]
 #include\ <embree3/rtcore_ray.h>
 
-struct\ RTCORE_ALIGN(16)\ RTCRay
+struct\ RTC_ALIGN(16)\ RTCRay
 {
-\ \ float\ org_x;\ \ \ \ \ \ \ \ //!<\ x\ coordinate\ of\ ray\ origin
-\ \ float\ org_y;\ \ \ \ \ \ \ \ //!<\ y\ coordinate\ of\ ray\ origin
-\ \ float\ org_z;\ \ \ \ \ \ \ \ //!<\ z\ coordinate\ of\ ray\ origin
-\ \ float\ tnear;\ \ \ \ \ \ \ \ //!<\ Start\ of\ ray\ segment
+\ \ float\ org_x;\ \ \ \ \ \ \ \ //\ x\ coordinate\ of\ ray\ origin
+\ \ float\ org_y;\ \ \ \ \ \ \ \ //\ y\ coordinate\ of\ ray\ origin
+\ \ float\ org_z;\ \ \ \ \ \ \ \ //\ z\ coordinate\ of\ ray\ origin
+\ \ float\ tnear;\ \ \ \ \ \ \ \ //\ start\ of\ ray\ segment
 
-\ \ float\ dir_x;\ \ \ \ \ \ \ \ //!<\ x\ coordinate\ of\ ray\ direction
-\ \ float\ dir_y;\ \ \ \ \ \ \ \ //!<\ y\ coordinate\ of\ ray\ direction
-\ \ float\ dir_z;\ \ \ \ \ \ \ \ //!<\ z\ coordinate\ of\ ray\ direction
-\ \ float\ tfar;\ \ \ \ \ \ \ \ \ //!<\ End\ of\ ray\ segment\ (set\ to\ hit\ distance)
+\ \ float\ dir_x;\ \ \ \ \ \ \ \ //\ x\ coordinate\ of\ ray\ direction
+\ \ float\ dir_y;\ \ \ \ \ \ \ \ //\ y\ coordinate\ of\ ray\ direction
+\ \ float\ dir_z;\ \ \ \ \ \ \ \ //\ z\ coordinate\ of\ ray\ direction
+\ \ float\ time;\ \ \ \ \ \ \ \ \ //\ time\ of\ this\ ray\ for\ motion\ blur
 
-\ \ float\ time;\ \ \ \ \ \ \ \ \ \ //!<\ Time\ of\ this\ ray\ for\ motion\ blur
-\ \ unsigned\ mask;\ \ \ \ \ \ \ //!<\ Used\ to\ mask\ out\ objects\ during\ traversal
-
-\ \ unsigned\ int\ id;\ \ \ \ //!<\ ray\ ID
-\ \ unsigned\ int\ flags;\ //!<\ ray\ flags
-\ \ 
-\ \ /*\ hit\ data\ */
-\ \ float\ Ng_x;\ \ \ \ \ \ \ \ \ //!<\ x\ coordinate\ of\ geometry\ normal
-\ \ float\ Ng_y;\ \ \ \ \ \ \ \ \ //!<\ y\ coordinate\ of\ geometry\ normal
-\ \ float\ Ng_z;\ \ \ \ \ \ \ \ \ //!<\ z\ coordinate\ of\ geometry\ normal
-\ \ \ 
-\ \ float\ u;\ \ \ \ \ \ \ \ \ \ \ //!<\ Barycentric\ u\ coordinate\ of\ hit
-\ \ float\ v;\ \ \ \ \ \ \ \ \ \ \ //!<\ Barycentric\ v\ coordinate\ of\ hit
-
-\ \ unsigned\ primID;\ \ \ //!<\ primitive\ ID\ of\ hit\ primitive
-\ \ unsigned\ geomID;\ \ \ //!<\ geometry\ ID\ of\ hit\ geometry
-\ \ unsigned\ instID;\ \ \ //!<\ instance\ ID\ of\ hit\ instance
+\ \ float\ tfar;\ \ \ \ \ \ \ \ \ //\ end\ of\ ray\ segment\ (set\ to\ hit\ distance)
+\ \ unsigned\ int\ mask;\ \ //\ ray\ mask
+\ \ unsigned\ int\ id;\ \ \ \ //\ ray\ ID
+\ \ unsigned\ int\ flags;\ //\ ray\ flags
 };
 \f[]
 .fi
@@ -52,22 +39,29 @@ The ray contains the origin (\f[C]org_x\f[], \f[C]org_y\f[],
 \f[C]dir_y\f[], \f[C]dir_z\f[] members), and ray segment (\f[C]tnear\f[]
 and \f[C]tfar\f[] members).
 The ray direction does not have to be normalized, and only the parameter
-range specified by the tnear/tfar interval is considered valid.
+range specified by the \f[C]tnear\f[]/\f[C]tfar\f[] interval is
+considered valid.
 .PP
-The ray segment has to be in the range [0, ∞], thus ranges that start
+The ray segment must be in the range [0, ∞], thus ranges that start
 behind the ray origin are not allowed, but ranges can reach to infinity.
-For rays inside a ray stream, tfar>tnear identifies inactive rays.
+For rays inside a ray stream, \f[C]tfar\f[] < \f[C]tnear\f[] identifies
+an inactive ray.
 .PP
 The ray further contains a motion blur time in the range [0, 1]
 (\f[C]time\f[] member), a ray mask (\f[C]mask\f[] member), a ray ID
-(\f[C]id\f[] member), and some ray flags (\f[C]flags\f[] member).
+(\f[C]id\f[] member), and ray flags (\f[C]flags\f[] member).
+The ray mask can be used to mask out some geometries for some rays (see
+\f[C]rtcSetGeometryMask\f[] for more details).
+The ray ID can be used to identify a ray inside a callback function,
+even if the order of rays inside a ray packet or stream has changed.
+The ray flags are reserved.
 .PP
 The \f[C]embree3/rtcore_ray.h\f[] header additionally defines the same
-ray structure in structure of array layout (SOA) for API functions
+ray structure in structure of array (SOA) layout for API functions
 accepting ray packets of size 4 (\f[C]RTCRay4\f[] type), size 8
 (\f[C]RTCRay8\f[] type), and size 16 (\f[C]RTCRay16\f[] type).
-The header additionally defines an \f[C]RTCRayNt\f[] template to
-generate ray packets of an arbitrary compile time size.
+The header additionally defines an \f[C]RTCRayNt\f[] template for ray
+packets of an arbitrary compile\-time size.
 .SS EXIT STATUS
 .SS SEE ALSO
 .PP

man/man3/RTCRay.3embree3

@@ -0,0 +1,37 @@
+.TH "RTCRay" "3" "" "" "Embree Ray Tracing Kernels 3"
+.SS NAME
+.IP
+.nf
+\f[C]
+RTCRayHit\ \-\ combined\ single\ ray/hit\ structure
+\f[]
+.fi
+.SS SYNOPSIS
+.IP
+.nf
+\f[C]
+#include\ <embree3/rtcore_ray.h>
+
+struct\ RTCORE_ALIGN(16)\ RTCRayHit
+{
+\ \ struct\ RTCRay\ ray;
+\ \ struct\ RTCHit\ hit;
+};
+\f[]
+.fi
+.SS DESCRIPTION
+.PP
+The \f[C]RTCRayHit\f[] structure is used as input for the
+\f[C]rtcIntersect\f[]\-type functions and stores the ray to intersect
+and some hit fields that hold the intersection result afterwards.
+.PP
+The \f[C]embree3/rtcore_ray.h\f[] header additionally defines the same
+ray/hit structure in structure of array (SOA) layout for API functions
+accepting ray packets of size 4 (\f[C]RTCRayHit4\f[] type), size 8
+(\f[C]RTCRayHit8\f[] type), and size 16 (\f[C]RTCRayHit16\f[] type).
+The header additionally defines an \f[C]RTCRayHitNt\f[] template to
+generate ray/hit packets of an arbitrary compile\-time size.
+.SS EXIT STATUS
+.SS SEE ALSO
+.PP
+[RTCRay], [RTCHit]

man/man3/RTCRayHit.3embree3

@@ -0,0 +1,40 @@
+.TH "RTCRayHitN" "3" "" "" "Embree Ray Tracing Kernels 3"
+.SS NAME
+.IP
+.nf
+\f[C]
+RTCRayHitN\ \-\ combined\ ray/hit\ packet\ of\ runtime\ size
+\f[]
+.fi
+.SS SYNOPSIS
+.IP
+.nf
+\f[C]
+#include\ <embree3/rtcore_ray.h>
+
+struct\ RTCRayHitN;
+
+struct\ RTCRayN*\ RTCRayHitN_RayN(struct\ RTCRayHitN*\ rayhit,\ unsigned\ int\ N);
+struct\ RTCHitN*\ RTCRayHitN_HitN(struct\ RTCRayHitN*\ rayhit,\ unsigned\ int\ N);
+\f[]
+.fi
+.SS DESCRIPTION
+.PP
+When the packet size of a ray/hit structure is not known at compile time
+(e.g.
+when Embree returns a ray/hit packet in the
+\f[C]RTCIntersectFunctionN\f[] callback function), Embree uses the
+\f[C]RTCRayHitN\f[] type for ray packets.
+These ray/hit packets can only have sizes of 1, 4, 8, or 16.
+No other packet size will be used.
+.PP
+You can either implement different special code paths for each of these
+possible packet sizes and cast the ray/hit to the appropriate ray/hit
+packet type, or extract the \f[C]RTCRayN\f[] and \f[C]RTCHitN\f[]
+components using the \f[C]rtcGetRayN\f[] and \f[C]rtcGetHitN\f[] helper
+functions and use the \f[C]RTCRayN_XXX\f[] and \f[C]RTCHitN_XXX\f[]
+functions to access the ray and hit parts of the structure.
+.SS EXIT STATUS
+.SS SEE ALSO
+.PP
+[RTCHitN]