1rtcSetGeometryIntersectFilEtmebrrFeuencRtaiyonT(r3ar)cticnSgetKGeeronmeeltsry3IntersectFilterFunction(3)
2
3
4
5   NAME
6              rtcSetGeometryIntersectFilterFunction - sets the intersection filter
7                for the geometry
8
9   SYNOPSIS
10              #include <embree3/rtcore.h>
11
12              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
22              typedef void (*RTCFilterFunctionN)(
23                const struct RTCFilterFunctionNArguments* args
24              );
25
26              void rtcSetGeometryIntersectFilterFunction(
27                RTCGeometry geometry,
28                RTCFilterFunctionN filter
29              );
30
31   DESCRIPTION
32       The  rtcSetGeometryIntersectFilterFunction function registers an inter‐
33       section filter callback function (filter argument)  for  the  specified
34       geometry (geometry argument).
35
36       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
41       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
48       If  the RTC_BUILD_QUALITY_HIGH 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
55       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
68       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
77       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
84   EXIT STATUS
85       On  failure  an  error  code is set that can be queried using rtcGetDe‐
86       viceError.
87
88   SEE ALSO
89       [rtcSetGeometryOccludedFilterFunction]
90
91
92
93                                      rtcSetGeometryIntersectFilterFunction(3)
Impressum