updated documentation

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

@@ -0,0 +1,52 @@
+.TH "RTCHit" "3" "" "" "Embree Ray Tracing Kernels 3"
+.SS NAME
+.IP
+.nf
+\f[C]
+RTCHit\ \-\ single\ hit\ structure
+\f[]
+.fi
+.SS SYNOPSIS
+.IP
+.nf
+\f[C]
+#include\ <embree3/rtcore.h>
+
+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\ u;\ \ \ \ \ \ \ \ \ \ \ \ \ //\ barycentric\ u\ coordinate\ of\ hit
+\ \ float\ v;\ \ \ \ \ \ \ \ \ \ \ \ \ //\ barycentric\ v\ coordinate\ of\ hit
+
+\ \ 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.
+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 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 (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 for hit
+packets of an arbitrary compile\-time size.
+.SS EXIT STATUS
+.SS SEE ALSO
+.PP
+[RTCRay]

man/man3/RTCHit.3embree3

@@ -0,0 +1,50 @@
+.TH "RTCHitN" "3" "" "" "Embree Ray Tracing Kernels 3"
+.SS NAME
+.IP
+.nf
+\f[C]
+RTCHitN\ \-\ hit\ packet\ of\ runtime\ size
+\f[]
+.fi
+.SS SYNOPSIS
+.IP
+.nf
+\f[C]
+#include\ <embree3/rtcore.h>
+
+struct\ HitN;
+
+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);
+
+float&\ RTCHitN_u(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCHitN_v(RTCHitN*\ hit,\ unsigned\ int\ N,\ unsigned\ int\ 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 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 appropriate hit packet
+type, or implement one general code path that uses the
+\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]hit\f[]
+argument), the packet size (\f[C]N\f[] argument), and returns a
+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
+[RTCRayN]

man/man3/RTCHitN.3embree3

@@ -0,0 +1,68 @@
+.TH "RTCRay" "3" "" "" "Embree Ray Tracing Kernels 3"
+.SS NAME
+.IP
+.nf
+\f[C]
+RTCRay\ \-\ single\ ray\ structure
+\f[]
+.fi
+.SS SYNOPSIS
+.IP
+.nf
+\f[C]
+#include\ <embree3/rtcore_ray.h>
+
+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\ 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\ 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
+.SS DESCRIPTION
+.PP
+The \f[C]RTCRay\f[] structure defines the ray layout for a single ray.
+The ray contains the origin (\f[C]org_x\f[], \f[C]org_y\f[],
+\f[C]org_z\f[] members), direction vector (\f[C]dir_x\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 \f[C]tnear\f[]/\f[C]tfar\f[] interval is
+considered valid.
+.PP
+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, \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 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 (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 for ray
+packets of an arbitrary compile\-time size.
+.SS EXIT STATUS
+.SS SEE ALSO
+.PP
+[RTCHit]

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]

man/man3/RTCRayHitN.3embree3

@@ -0,0 +1,55 @@
+.TH "RTCRayN" "3" "" "" "Embree Ray Tracing Kernels 3"
+.SS NAME
+.IP
+.nf
+\f[C]
+RTCRayN\ \-\ ray\ packet\ of\ runtime\ size
+\f[]
+.fi
+.SS SYNOPSIS
+.IP
+.nf
+\f[C]
+#include\ <embree3/rtcore_ray.h>
+
+struct\ RTCRayN;
+
+float&\ RTCRayN_org_x(RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCRayN_org_y(RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCRayN_org_z(RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCRayN_tnear(RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+
+float&\ RTCRayN_dir_x(RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCRayN_dir_y(RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCRayN_dir_z(RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+float&\ RTCRayN_time\ (RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+
+float&\ \ \ \ RTCRayN_tfar\ (RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+unsigned&\ RTCRayN_mask\ (RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+unsigned&\ RTCRayN_id\ \ \ (RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+unsigned&\ RTCRayN_flags(RTCRayN*\ ray,\ unsigned\ int\ N,\ unsigned\ int\ i);
+\f[]
+.fi
+.SS DESCRIPTION
+.PP
+When the ray packet size is not known at compile time (e.g.
+when Embree returns a ray packet in the \f[C]RTCFilterFuncN\f[] callback
+function), Embree uses the \f[C]RTCRayN\f[] type for ray packets.
+These ray 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 to the appropriate ray packet
+type, or implement one general code path that uses the
+\f[C]RTCRayN_XXX\f[] helper functions to access the ray packet
+components.
+.PP
+These helper functions get a pointer to the ray packet (\f[C]ray\f[]
+argument), the packet size (\f[C]N\f[] argument), and returns a
+reference to a component (e.g.
+x\-component of origin) of the the i\-th ray of the packet (\f[C]i\f[]
+argument).
+.SS EXIT STATUS
+.SS SEE ALSO
+.PP
+[RTCHitN]