.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "rtcSetGeometryIntersectFunction" "3" "" "" "Embree Ray Tracing Kernels 4"
.hy
.SS NAME
.IP
.nf
\f[C]
rtcSetGeometryIntersectFunction - sets the callback function to
  intersect a user geometry
\f[R]
.fi
.SS SYNOPSIS
.IP
.nf
\f[C]
#include <embree4/rtcore.h>

struct RTCIntersectFunctionNArguments
{
  int* valid;
  void* geometryUserPtr;
  unsigned int primID;
  struct RTCRayQueryContext* context;
  struct RTCRayHitN* rayhit;
  unsigned int N;
  unsigned int geomID;
};

typedef void (*RTCIntersectFunctionN)(
  const struct RTCIntersectFunctionNArguments* args
);

void rtcSetGeometryIntersectFunction(
  RTCGeometry geometry,
  RTCIntersectFunctionN intersect
);
\f[R]
.fi
.SS DESCRIPTION
.PP
The \f[C]rtcSetGeometryIntersectFunction\f[R] function registers a
ray/primitive intersection callback function (\f[C]intersect\f[R]
argument) for the specified user geometry (\f[C]geometry\f[R] argument).
.PP
Only a single callback function can be registered per geometry and
further invocations overwrite the previously set callback function.
Passing \f[C]NULL\f[R] as function pointer disables the registered
callback function.
.PP
The registered callback function is invoked by
\f[C]rtcIntersect\f[R]-type ray queries to calculate the intersection of
a ray packet of variable size with one user-defined primitive.
The callback function of type \f[C]RTCIntersectFunctionN\f[R] gets
passed a number of arguments through the
\f[C]RTCIntersectFunctionNArguments\f[R] structure.
The value \f[C]N\f[R] specifies the ray packet size, \f[C]valid\f[R]
points to an array of integers that specify whether the corresponding
ray is valid (-1) or invalid (0), the \f[C]geometryUserPtr\f[R] member
points to the geometry user data previously set through
\f[C]rtcSetGeometryUserData\f[R], the \f[C]context\f[R] member points to
the ray query context passed to the ray query, the \f[C]rayhit\f[R]
member points to a ray and hit packet of variable size \f[C]N\f[R], and
the \f[C]geomID\f[R] and \f[C]primID\f[R] member identifies the geometry
ID and primitive ID of the primitive to intersect.
.PP
The \f[C]ray\f[R] component of the \f[C]rayhit\f[R] structure contains
valid data, in particular the \f[C]tfar\f[R] value is the current
closest hit distance found.
All data inside the \f[C]hit\f[R] component of the \f[C]rayhit\f[R]
structure are undefined and should not be read by the function.
.PP
The task of the callback function is to intersect each active ray from
the ray packet with the specified user primitive.
If the user-defined primitive is missed by a ray of the ray packet, the
function should return without modifying the ray or hit.
If an intersection of the user-defined primitive with the ray was found
in the valid range (from \f[C]tnear\f[R] to \f[C]tfar\f[R]), it should
update the hit distance of the ray (\f[C]tfar\f[R] member) and the hit
(\f[C]u\f[R], \f[C]v\f[R], \f[C]Ng\f[R], \f[C]instID\f[R],
\f[C]geomID\f[R], \f[C]primID\f[R] members).
In particular, the currently intersected instance is stored in the
\f[C]instID\f[R] field of the ray query context, which must be deep
copied into the \f[C]instID\f[R] member of the hit.
.PP
As a primitive might have multiple intersections with a ray, the
intersection filter function needs to be invoked by the user geometry
intersection callback for each encountered intersection, if filtering of
intersections is desired.
This can be achieved through the
\f[C]rtcInvokeIntersectFilterFromGeometry\f[R] call.
.PP
Within the user geometry intersect function, it is safe to trace new
rays and create new scenes and geometries.
.IP
.nf
\f[C]
\f[R]
.fi
.SS EXIT STATUS
.PP
On failure an error code is set that can be queried using
\f[C]rtcGetDeviceError\f[R].
.SS SEE ALSO
.PP
[rtcSetGeometryOccludedFunction], [rtcSetGeometryUserData],
[rtcInvokeIntersectFilterFromGeometry]