Description This function evaluates whether a is incident on (or departing from) the side of a surface corresponding to its positive or negative surface normal. The function returns a boolean indicating whether it was successful in calculating the requested information. The surface whose side is being evaluated is whichever surface the ray interacted with most recently in the raytrace (indicated by "entity" member of the ray's T_RAY structure).
If the ray ID number that is passed to the function corresponds to an empty ray slot or a ray that has previously been deleted, the function will halt with an error. Empty ray slots may occur during multi-threaded raytracing (see the multi-threading help topic for more information), so the user should always use an appropriate ray buffer loop structure or otherwise check that the ray ID is a live ray using the IsRayLive function.
The raytrace control and coating properties on a given surface will dictate whether a ray's departure angle can be calculated. If the raytrace control on a surface is Halt All, for example, incident rays cannot transmit/reflect from the surface and therefor no departure angle can be calculated. In this case, the bSuccess flag will return False and the value of dAng should not be used.
Depending on the number of rays traced, it may be necessary to dimension ray index and ray counter variables as data type Huge_ instead of Long. Please see Multi-threaded Raytracing for more information.
Syntax bSuccess = GetRayIncidentOrDepartureSidedness( nRay, bWantIncident, sidedness )
Parameters bSuccess As Boolean Returned boolean indicating whether the evaluation was successful.
nRay As Long (or Huge_) ID number of the ray whose sidedness value is being requested.
bWantIncident As Boolean Boolean flag that specifies whether the calculation should be performed for the ray's incident direction or departure direction. When True, the sidedness value is attempted to be calculated for the ray's incident direction.
sidedness As Long After execution, this variable contains the result of the sidedness calculation (assuming bSuccess is True). A value of -1 indicates that the ray's direction vector (incident or departure, as given by bWantIncident) is on the negative surface normal side of the surface. A value of +1 indicates that the ray's direction vector (incident or departure, as given by bWantIncident) is on the positive surface normal side of the surface.
Example The example below demonstrates how to query a specific ray in the buffer for its sidedness value with respect to the current surface the ray is associated with.
Dim success As Boolean, wantIncident As Boolean Dim curRay As Long, sidedness As Long curRay = 0 wantIncident = False
If IsRayLive( curRay ) Then success = GetRayIncidentOrDepartureSidedness( curRay, wantIncident, sidedness ) Print "Evaluation success = " & success Print "Wanted incident side? = " & wantIncident Print "Sidedness value = " & sidedness Else Print "No live ray at the requested ray buffer index." End If
End Sub
See Also GetRayIncidentOrDepartureAngle
|