1rtcSetGeometryIntersectFilEtmebrrFeuencRtaiyonT(r3ar)cticnSgetKGeeronmeeltsry3IntersectFilterFunction(3)
2 NAME
6 rtcSetGeometryIntersectFilterFunction - sets the intersection filter
7 for the geometry
8 SYNOPSIS
10 #include <embree3/rtcore.h>
11 struct RTCFilterFunctionNArguments
13 {
14 int* valid;
15 void* geometryUserPtr;
16 const struct RTCIntersectContext* context;
17 struct RTCRayN* ray;
18 struct RTCHitN* hit;
19 unsigned int N;
20 };
21 typedef void (*RTCFilterFunctionN)(
23 const struct RTCFilterFunctionNArguments* args
24 );
25 void rtcSetGeometryIntersectFilterFunction(
27 RTCGeometry geometry,
28 RTCFilterFunctionN filter
29 );
30 DESCRIPTION
32 The rtcSetGeometryIntersectFilterFunction function registers an inter‐
33 section filter callback function (filter argument) for the specified
34 geometry (geometry argument).
35 Only a single callback function can be registered per geometry, and
37 further invocations overwrite the previously set callback function.
38 Passing NULL as function pointer disables the registered callback func‐
39 tion.
40 The registered intersection filter function is invoked for every hit
42 encountered during the rtcIntersect-type ray queries and can accept or
43 reject that hit. The feature can be used to define a silhouette for a
44 primitive and reject hits that are outside the silhouette. E.g. a
45 tree leaf could be modeled with an alpha texture that decides whether
46 hit points lie inside or outside the leaf.
47 If the RTC_SCENE_HIGH_QUALITY mode is set, the filter functions may be
49 called multiple times for the same primitive hit. Further, rays hit‐
50 ting exactly the edge might also report two hits for the same surface.
51 For certain use cases, the application may have to work around this
52 limitation by collecting already reported hits (geomID/primID pairs)
53 and ignoring duplicates.
54 The filter function callback of type RTCFilterFunctionN gets passed a
56 number of arguments through the RTCFilterFunctionNArguments structure.
57 The valid parameter of that structure points to an integer valid mask
58 (0 means invalid and -1 means valid). The geometryUserPtr member is a
59 user pointer optionally set per geometry through the rtcSetGeome‐
60 tryUserData function. The context member points to the intersection
61 context passed to the ray query function. The ray parameter points to
62 N rays in SOA layout. The hit parameter points to N hits in SOA layout
63 to test. The N parameter is the number of rays and hits in ray and
64 hit. The hit distance is provided as the tfar value of the ray. If
65 the hit geometry is instanced, the instID member of the ray is valid,
66 and the ray and the potential hit are in object space.
67 The filter callback function has the task to check for each valid ray
69 whether it wants to accept or reject the corresponding hit. To reject
70 a hit, the filter callback function just has to write 0 to the integer
71 valid mask of the corresponding ray. To accept the hit, it just has to
72 leave the valid mask set to -1. The filter function is further allowed
73 to change the hit and decrease the tfar value of the ray but it should
74 not modify other ray data nor any inactive components of the ray or
75 hit.
76 The implementation of the filter function can choose to implement a
78 single code path that uses the ray access helper functions RTCRay_XXX
79 and hit access helper functions RTCHit_XXX to access ray and hit data.
80 Alternatively the code can branch to optimized implementations for spe‐
81 cific sizes of N and cast the ray and hit inputs to the proper packet
82 types.
83 EXIT STATUS
85 On failure an error code is set that can be queried using rtcGetDe‐
86 viceError.
87 SEE ALSO
89 [rtcSetGeometryOccludedFilterFunction]
90 rtcSetGeometryIntersectFilterFunction(3)