rtcSetGeometryIntersectFilterFunction.3embree3

NAME

rtcSetGeometryIntersectFilterFunction - sets the intersection filter
  for the geometry

SYNOPSIS

#include <embree3/rtcore.h>

struct RTCFilterFunctionNArguments
{
  int* valid;
  void* geometryUserPtr;
  const struct RTCIntersectContext* context;
  struct RTCRayN* ray;
  struct RTCHitN* hit;
  unsigned int N;
};

typedef void (*RTCFilterFunctionN)(
  const struct RTCFilterFunctionNArguments* args
);

void rtcSetGeometryIntersectFilterFunction(
  RTCGeometry geometry,
  RTCFilterFunctionN filter
);

DESCRIPTION

The rtcSetGeometryIntersectFilterFunction function registers an intersection filter callback function (filter argument) for the specified geometry (geometry argument).

Only a single callback function can be registered per geometry, and further invocations overwrite the previously set callback function. Passing NULL as function pointer disables the registered callback function.

The registered intersection filter function is invoked for every hit encountered during the rtcIntersect-type ray queries and can accept or reject that hit. The feature can be used to define a silhouette for a primitive and reject hits that are outside the silhouette. E.g. a tree leaf could be modeled with an alpha texture that decides whether hit points lie inside or outside the leaf.

If the RTC_BUILD_QUALITY_HIGH mode is set, the filter functions may be called multiple times for the same primitive hit. Further, rays hitting exactly the edge might also report two hits for the same surface. For certain use cases, the application may have to work around this limitation by collecting already reported hits (geomID/primID pairs) and ignoring duplicates.

The filter function callback of type RTCFilterFunctionN gets passed a number of arguments through the RTCFilterFunctionNArguments structure. The valid parameter of that structure points to an integer valid mask (0 means invalid and -1 means valid). The geometryUserPtr member is a user pointer optionally set per geometry through the rtcSetGeometryUserData function. The context member points to the intersection context passed to the ray query function. The ray parameter points to N rays in SOA layout. The hit parameter points to N hits in SOA layout to test. The N parameter is the number of rays and hits in ray and hit. The hit distance is provided as the tfar value of the ray. If the hit geometry is instanced, the instID member of the ray is valid, and the ray and the potential hit are in object space.

The filter callback function has the task to check for each valid ray whether it wants to accept or reject the corresponding hit. To reject a hit, the filter callback function just has to write 0 to the integer valid mask of the corresponding ray. To accept the hit, it just has to leave the valid mask set to -1. The filter function is further allowed to change the hit and decrease the tfar value of the ray but it should not modify other ray data nor any inactive components of the ray or hit.

The implementation of the filter function can choose to implement a single code path that uses the ray access helper functions RTCRay_XXX and hit access helper functions RTCHit_XXX to access ray and hit data. Alternatively the code can branch to optimized implementations for specific sizes of N and cast the ray and hit inputs to the proper packet types.

EXIT STATUS

On failure an error code is set that can be queried using rtcGetDeviceError.

SEE ALSO

[rtcSetGeometryOccludedFilterFunction]