From 34e256609a686a707f882af6b8ca44dc0663720a Mon Sep 17 00:00:00 2001 From: Ali Shakiba Date: Mon, 1 Apr 2024 16:55:16 +0330 Subject: [PATCH] update ray cast docs and minor bug fix --- docs/api/classes/broadphase.md | 2 +- docs/api/classes/dynamictree.md | 2 +- docs/api/classes/world.md | 2 +- docs/api/globals.md | 20 +++++++++----------- src/collision/BroadPhase.ts | 2 +- src/collision/DynamicTree.ts | 8 +++----- src/dynamics/World.ts | 19 ++++++++++--------- 7 files changed, 26 insertions(+), 29 deletions(-) diff --git a/docs/api/classes/broadphase.md b/docs/api/classes/broadphase.md index a55cf0d4..e1ed3927 100644 --- a/docs/api/classes/broadphase.md +++ b/docs/api/classes/broadphase.md @@ -262,7 +262,7 @@ number of proxies in the tree. Name | Type | Description | ------ | ------ | ------ | `input` | [RayCastInput](../interfaces/raycastinput.md) | The ray-cast input data. The ray extends from `p1` to `p1 + maxFraction * (p2 - p1)`. | -`rayCastCallback` | [RayCastCallback](../globals.md#raycastcallback) | A function that is called for each proxy that is hit by the ray. | +`rayCastCallback` | [RayCastCallback](../globals.md#raycastcallback) | A function that is called for each proxy that is hit by the ray. If the return value is a positive number it will update the maxFraction of the ray cast input, and if it is zero it will terminate they ray cast. | **Returns:** *void* diff --git a/docs/api/classes/dynamictree.md b/docs/api/classes/dynamictree.md index 3721ed0c..c69b22d4 100644 --- a/docs/api/classes/dynamictree.md +++ b/docs/api/classes/dynamictree.md @@ -316,7 +316,7 @@ number of proxies in the tree. Name | Type | Description | ------ | ------ | ------ | `input` | [RayCastInput](../interfaces/raycastinput.md) | The ray-cast input data. The ray extends from `p1` to `p1 + maxFraction * (p2 - p1)`. | -`rayCastCallback` | [RayCastCallback](../globals.md#raycastcallback) | A function that is called for each proxy that is hit by the ray. | +`rayCastCallback` | [RayCastCallback](../globals.md#raycastcallback) | A function that is called for each proxy that is hit by the ray. If the return value is a positive number it will update the maxFraction of the ray cast input, and if it is zero it will terminate they ray cast. | **Returns:** *void* diff --git a/docs/api/classes/world.md b/docs/api/classes/world.md index 32097ee2..ef2ba64a 100644 --- a/docs/api/classes/world.md +++ b/docs/api/classes/world.md @@ -774,7 +774,7 @@ Name | Type | Description | ------ | ------ | ------ | `point1` | Vec2 | The ray starting point | `point2` | Vec2 | The ray ending point | -`callback` | [WorldRayCastCallback](../globals.md#worldraycastcallback) | A user implemented callback function. | +`callback` | [WorldRayCastCallback](../globals.md#worldraycastcallback) | A function that is called for each fixture that is hit by the ray. You control how the ray cast proceeds by returning a numeric/float value. | **Returns:** *void* diff --git a/docs/api/globals.md b/docs/api/globals.md index 00436180..7ed90045 100644 --- a/docs/api/globals.md +++ b/docs/api/globals.md @@ -319,10 +319,14 @@ ___ Callback function for ray casts, see [World.rayCast](classes/world.md#raycast). -Called for each fixture found in the query. You control how the ray cast -proceeds by returning a float: return -1: ignore this fixture and continue -return 0: terminate the ray cast return fraction: clip the ray to this point -return 1: don't clip the ray and continue +Called for each fixture found in the query. +The returned value replaces the ray-cast input maxFraction. +You control how the ray cast proceeds by returning a numeric/float value. + +- `0` to terminate the ray cast +- `fraction` to clip the ray cast at current point +- `1` don't clip the ray and continue +- `-1` (or anything else) to continue **`param`** The fixture hit by the ray @@ -332,13 +336,7 @@ return 1: don't clip the ray and continue **`param`** The fraction along the ray at the point of intersection -**`returns`** `-1` to ignore the current fixture and continue - -**`returns`** `0` to terminate the ray cast - -**`returns`** `fraction` to clip the raycast at current point - -**`returns`** `1` don't clip the ray and continue +**`returns`** A number to update the maxFraction #### Type declaration: diff --git a/src/collision/BroadPhase.ts b/src/collision/BroadPhase.ts index 4e2ea957..54e090a0 100644 --- a/src/collision/BroadPhase.ts +++ b/src/collision/BroadPhase.ts @@ -111,7 +111,7 @@ export class BroadPhase { * number of proxies in the tree. * * @param input The ray-cast input data. The ray extends from `p1` to `p1 + maxFraction * (p2 - p1)`. - * @param rayCastCallback A function that is called for each proxy that is hit by the ray. + * @param rayCastCallback A function that is called for each proxy that is hit by the ray. If the return value is a positive number it will update the maxFraction of the ray cast input, and if it is zero it will terminate they ray cast. */ rayCast(input: RayCastInput, rayCastCallback: RayCastCallback): void { this.m_tree.rayCast(input, rayCastCallback); diff --git a/src/collision/DynamicTree.ts b/src/collision/DynamicTree.ts index 49abcf41..70df00f4 100644 --- a/src/collision/DynamicTree.ts +++ b/src/collision/DynamicTree.ts @@ -768,7 +768,7 @@ export class DynamicTree { * number of proxies in the tree. * * @param input The ray-cast input data. The ray extends from `p1` to `p1 + maxFraction * (p2 - p1)`. - * @param rayCastCallback A function that is called for each proxy that is hit by the ray. + * @param rayCastCallback A function that is called for each proxy that is hit by the ray. If the return value is a positive number it will update the maxFraction of the ray cast input, and if it is zero it will terminate they ray cast. */ rayCast(input: RayCastInput, rayCastCallback: RayCastCallback): void { // TODO: GC @@ -825,10 +825,8 @@ export class DynamicTree { if (value === 0.0) { // The client has terminated the ray cast. - return; - } - - if (value > 0.0) { + break; + } else if (value > 0.0) { // update segment bounding box. maxFraction = value; t = Vec2.combine((1 - maxFraction), p1, maxFraction, p2); diff --git a/src/dynamics/World.ts b/src/dynamics/World.ts index 7afb495f..fc3f92f6 100644 --- a/src/dynamics/World.ts +++ b/src/dynamics/World.ts @@ -78,20 +78,21 @@ export interface WorldDef { /** * Callback function for ray casts, see {@link World.rayCast}. * - * Called for each fixture found in the query. You control how the ray cast - * proceeds by returning a float: return -1: ignore this fixture and continue - * return 0: terminate the ray cast return fraction: clip the ray to this point - * return 1: don't clip the ray and continue + * Called for each fixture found in the query. + * The returned value replaces the ray-cast input maxFraction. + * You control how the ray cast proceeds by returning a numeric/float value. + * + * - `0` to terminate the ray cast + * - `fraction` to clip the ray cast at current point + * - `1` don't clip the ray and continue + * - `-1` (or anything else) to continue * * @param fixture The fixture hit by the ray * @param point The point of initial intersection * @param normal The normal vector at the point of intersection * @param fraction The fraction along the ray at the point of intersection * - * @return `-1` to ignore the current fixture and continue - * @return `0` to terminate the ray cast - * @return `fraction` to clip the raycast at current point - * @return `1` don't clip the ray and continue + * @returns A number to update the maxFraction */ export type WorldRayCastCallback = (fixture: Fixture, point: Vec2, normal: Vec2, fraction: number) => number; @@ -404,7 +405,7 @@ export class World { * * @param point1 The ray starting point * @param point2 The ray ending point - * @param callback A user implemented callback function. + * @param callback A function that is called for each fixture that is hit by the ray. You control how the ray cast proceeds by returning a numeric/float value. */ rayCast(point1: Vec2, point2: Vec2, callback: WorldRayCastCallback): void { _ASSERT && console.assert(typeof callback === 'function');