From fa291d4e4cd4277e52814889343f8fa8eba50e04 Mon Sep 17 00:00:00 2001
From: bloeys <bloeys@outlook.com>
Date: Sat, 19 Feb 2022 06:33:50 +0400
Subject: [PATCH] RaycastBuffer release+RaycastWithHitBuffer

---
 main.go                        |   9 +++--
 pgo/libs/libphysx-c.a          | Bin 23196 -> 23978 bytes
 pgo/pgo.go                     |  19 ++++++++++
 pgo/physx-c/CPxRaycastBuffer.h |  67 +++++++++++++++++++++++++++++++++
 pgo/physx-c/CPxScene.h         |  54 ++++----------------------
 5 files changed, 99 insertions(+), 50 deletions(-)
 create mode 100755 pgo/physx-c/CPxRaycastBuffer.h

diff --git a/main.go b/main.go
index 240755e..0a855ed 100755
--- a/main.go
+++ b/main.go
@@ -127,6 +127,9 @@ func main() {
 
 	//Run simulation
 	// r := bufio.NewReader(os.Stdin)
+	raycastBuffer := pgo.NewRaycastBuffer(1)
+	defer raycastBuffer.Release()
+
 	s.SetScratchBuffer(4)
 	for {
 		s.Collide(1 / 50.0)
@@ -134,9 +137,9 @@ func main() {
 		s.Advance()
 		s.FetchResults(true)
 
-		_, b := s.Raycast(pgo.NewVec3(0, 0, 0), pgo.NewVec3(0, 1, 0), 9)
-		if b.HasBlock() {
-			block := b.GetBlock()
+		s.RaycastWithHitBuffer(pgo.NewVec3(0, 0, 0), pgo.NewVec3(0, 1, 0), 9, raycastBuffer, 1)
+		if raycastBuffer.HasBlock() {
+			block := raycastBuffer.GetBlock()
 			d := block.GetDistance()
 			pos := block.GetPos()
 			fmt.Printf("Raycast hit at dist (%v) and post %v\n", d, pos.String())
diff --git a/pgo/libs/libphysx-c.a b/pgo/libs/libphysx-c.a
index a2679b73bbeb75d277bfc19834b6eda0e229d1ac..6fe69d109918d3ed6add20f618d34b47e33c010a 100755
GIT binary patch
delta 3004
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
E4+ahnN&o-=

delta 2529
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

diff --git a/pgo/pgo.go b/pgo/pgo.go
index 019aa07..e03f80b 100755
--- a/pgo/pgo.go
+++ b/pgo/pgo.go
@@ -135,6 +135,12 @@ func (s *Scene) Raycast(origin, unitDir *Vec3, distance float32) (bool, RaycastB
 	return bool(ret), rb
 }
 
+func (s *Scene) RaycastWithHitBuffer(origin, unitDir *Vec3, distance float32, rb *RaycastBuffer, touchesToRead uint) bool {
+
+	ret := C.CPxScene_raycastWithHitBuffer(s.cS, &origin.cV, &unitDir.cV, C.float(distance), rb.cRb, C.uint(touchesToRead))
+	return bool(ret)
+}
+
 type RaycastBuffer struct {
 	cRb *C.struct_CPxRaycastBuffer
 }
@@ -164,6 +170,19 @@ func (rb *RaycastBuffer) GetTouches() []RaycastHit {
 	return hits
 }
 
+func (rb *RaycastBuffer) Release() {
+	C.CPxRaycastBuffer_release(rb.cRb)
+}
+
+func NewRaycastBuffer(maxTouches uint32) *RaycastBuffer {
+
+	rb := &RaycastBuffer{
+		cRb: C.NewCPxRaycastBufferWithAlloc(C.uint(maxTouches)),
+	}
+
+	return rb
+}
+
 type RaycastHit struct {
 	cRh *C.struct_CPxRaycastHit
 }
diff --git a/pgo/physx-c/CPxRaycastBuffer.h b/pgo/physx-c/CPxRaycastBuffer.h
new file mode 100755
index 0000000..e2b46de
--- /dev/null
+++ b/pgo/physx-c/CPxRaycastBuffer.h
@@ -0,0 +1,67 @@
+#ifndef CPxRaycastBuffer_H
+#define CPxRaycastBuffer_H
+
+#include "CPxVec3.h"
+#include "CPxShape.h"
+#include "CPxRigidActor.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+	enum CPxHitFlag
+	{
+		CPxHitFlag_ePOSITION = (1 << 0),	//!< "position" member of #PxQueryHit is valid
+		CPxHitFlag_eNORMAL = (1 << 1),	//!< "normal" member of #PxQueryHit is valid
+		CPxHitFlag_eUV = (1 << 3),	//!< "u" and "v" barycentric coordinates of #PxQueryHit are valid. Not applicable to sweep queries.
+		CPxHitFlag_eASSUME_NO_INITIAL_OVERLAP = (1 << 4),	//!< Performance hint flag for sweeps when it is known upfront there's no initial overlap.
+		//!< NOTE: using this flag may cause undefined results if shapes are initially overlapping.
+		CPxHitFlag_eMESH_MULTIPLE = (1 << 5),	//!< Report all hits for meshes rather than just the first. Not applicable to sweep queries.
+		CPxHitFlag_eMESH_ANY = (1 << 6),	//!< Report any first hit for meshes. If neither eMESH_MULTIPLE nor eMESH_ANY is specified,
+		//!< a single closest hit will be reported for meshes.
+		CPxHitFlag_eMESH_BOTH_SIDES = (1 << 7),	//!< Report hits with back faces of mesh triangles. Also report hits for raycast
+		//!< originating on mesh surface and facing away from the surface normal. Not applicable to sweep queries.
+		//!< Please refer to the user guide for heightfield-specific differences.
+		CPxHitFlag_ePRECISE_SWEEP = (1 << 8),	//!< Use more accurate but slower narrow phase sweep tests.
+		//!< May provide better compatibility with PhysX 3.2 sweep behavior.
+		CPxHitFlag_eMTD = (1 << 9),	//!< Report the minimum translation depth, normal and contact point.
+		CPxHitFlag_eFACE_INDEX = (1 << 10),	//!< "face index" member of #PxQueryHit is valid
+		CPxHitFlag_eDEFAULT = CPxHitFlag_ePOSITION | CPxHitFlag_eNORMAL | CPxHitFlag_eFACE_INDEX,
+		/** \brief Only this subset of flags can be modified by pre-filter. Other modifications will be discarded. */
+		CPxHitFlag_eMODIFIABLE_FLAGS = CPxHitFlag_eMESH_MULTIPLE | CPxHitFlag_eMESH_BOTH_SIDES | CPxHitFlag_eASSUME_NO_INITIAL_OVERLAP | CPxHitFlag_ePRECISE_SWEEP
+	};
+
+	struct CPxRaycastHit
+	{
+		CENUM CPxHitFlag flags;			//!< Hit flags specifying which members contain valid values.
+		CSTRUCT CPxVec3	position;	//!< World-space hit position (flag: #PxHitFlag::ePOSITION)
+		CSTRUCT CPxVec3	normal;		//!< World-space hit normal (flag: #PxHitFlag::eNORMAL)
+
+		/**
+		\brief	Distance to hit.
+		\note	If the eMTD flag is used, distance will be a negative value if shapes are overlapping indicating the penetration depth.
+		\note	Otherwise, this value will be >= 0 */
+		CPxF32 distance;
+		CPxReal u, v;
+		CPxU32	faceIndex;
+		CSTRUCT CPxShape shape;
+		CSTRUCT CPxRigidActor actor;
+	};
+
+	struct CPxRaycastBuffer
+	{
+		CSTRUCT CPxRaycastHit block;
+		CSTRUCT CPxRaycastHit* touches;
+		CPxU32 nbTouches;
+		bool hasBlock;
+	};
+
+	CPxAPI CSTRUCT CPxRaycastBuffer* NewCPxRaycastBufferWithAlloc(CPxU32 maxTouches);
+	CPxAPI void CPxRaycastBuffer_release(CSTRUCT CPxRaycastBuffer* crb);
+
+#ifdef __cplusplus
+}
+#endif
+
+
+#endif // !CPxRaycastBuffer_H
diff --git a/pgo/physx-c/CPxScene.h b/pgo/physx-c/CPxScene.h
index d302618..64a0340 100755
--- a/pgo/physx-c/CPxScene.h
+++ b/pgo/physx-c/CPxScene.h
@@ -6,58 +6,12 @@
 #include "CPxVec3.h"
 #include "CPxShape.h"
 #include "CPxRigidActor.h"
+#include "CPxRaycastBuffer.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-	enum CPxHitFlag
-	{
-		CPxHitFlag_ePOSITION = (1 << 0),	//!< "position" member of #PxQueryHit is valid
-		CPxHitFlag_eNORMAL = (1 << 1),	//!< "normal" member of #PxQueryHit is valid
-		CPxHitFlag_eUV = (1 << 3),	//!< "u" and "v" barycentric coordinates of #PxQueryHit are valid. Not applicable to sweep queries.
-		CPxHitFlag_eASSUME_NO_INITIAL_OVERLAP = (1 << 4),	//!< Performance hint flag for sweeps when it is known upfront there's no initial overlap.
-		//!< NOTE: using this flag may cause undefined results if shapes are initially overlapping.
-		CPxHitFlag_eMESH_MULTIPLE = (1 << 5),	//!< Report all hits for meshes rather than just the first. Not applicable to sweep queries.
-		CPxHitFlag_eMESH_ANY = (1 << 6),	//!< Report any first hit for meshes. If neither eMESH_MULTIPLE nor eMESH_ANY is specified,
-		//!< a single closest hit will be reported for meshes.
-		CPxHitFlag_eMESH_BOTH_SIDES = (1 << 7),	//!< Report hits with back faces of mesh triangles. Also report hits for raycast
-		//!< originating on mesh surface and facing away from the surface normal. Not applicable to sweep queries.
-		//!< Please refer to the user guide for heightfield-specific differences.
-		CPxHitFlag_ePRECISE_SWEEP = (1 << 8),	//!< Use more accurate but slower narrow phase sweep tests.
-		//!< May provide better compatibility with PhysX 3.2 sweep behavior.
-		CPxHitFlag_eMTD = (1 << 9),	//!< Report the minimum translation depth, normal and contact point.
-		CPxHitFlag_eFACE_INDEX = (1 << 10),	//!< "face index" member of #PxQueryHit is valid
-		CPxHitFlag_eDEFAULT = CPxHitFlag_ePOSITION | CPxHitFlag_eNORMAL | CPxHitFlag_eFACE_INDEX,
-		/** \brief Only this subset of flags can be modified by pre-filter. Other modifications will be discarded. */
-		CPxHitFlag_eMODIFIABLE_FLAGS = CPxHitFlag_eMESH_MULTIPLE | CPxHitFlag_eMESH_BOTH_SIDES | CPxHitFlag_eASSUME_NO_INITIAL_OVERLAP | CPxHitFlag_ePRECISE_SWEEP
-	};
-
-	struct CPxRaycastHit
-	{
-		CENUM CPxHitFlag flags;			//!< Hit flags specifying which members contain valid values.
-		CSTRUCT CPxVec3	position;	//!< World-space hit position (flag: #PxHitFlag::ePOSITION)
-		CSTRUCT CPxVec3	normal;		//!< World-space hit normal (flag: #PxHitFlag::eNORMAL)
-
-		/**
-		\brief	Distance to hit.
-		\note	If the eMTD flag is used, distance will be a negative value if shapes are overlapping indicating the penetration depth.
-		\note	Otherwise, this value will be >= 0 */
-		CPxF32 distance;
-		CPxReal u, v;
-		CPxU32	faceIndex;
-		CSTRUCT CPxShape shape;
-		CSTRUCT CPxRigidActor actor;
-	};
-
-	struct CPxRaycastBuffer
-	{
-		CSTRUCT CPxRaycastHit block;
-		CSTRUCT CPxRaycastHit* touches;
-		CPxU32 nbTouches;
-		bool hasBlock;
-	};
-
 	struct CPxScene
 	{
 		void* obj;
@@ -72,8 +26,14 @@ extern "C" {
 	CPxAPI bool CPxScene_fetchCollision(CSTRUCT CPxScene*, bool block);
 	CPxAPI void CPxScene_advance(CSTRUCT CPxScene*);
 	CPxAPI bool CPxScene_fetchResults(CSTRUCT CPxScene*, bool block, CPxU32* errorState);
+
+	//Does a scene raycast. Allocates memory for hitRet and then reads data into it. It is the callers responsibility to free.
 	CPxAPI bool CPxScene_raycast(CSTRUCT CPxScene* cs, CSTRUCT CPxVec3* origin, CSTRUCT CPxVec3* unitDir, CPxReal distance, CSTRUCT CPxRaycastBuffer** hitRet);
 
+	//Does a scene raycast. 'hit' must be pre-allocated as NO new allocation will happen in the function.
+	//hit->touches will be filled up to 'touchesToRead' and must also be pre-allocated. If the hit produces more touches than 'touchesToRead' then the additional touches will be ignored.
+	CPxAPI bool CPxScene_raycastWithHitBuffer(CSTRUCT CPxScene* cs, CSTRUCT CPxVec3* origin, CSTRUCT CPxVec3* unitDir, CPxReal distance, CSTRUCT CPxRaycastBuffer* hit, CPxU32 touchesToRead);
+
 	/// <summary>
 	/// Creates a scratch buffer thats a multiple of 16K to be used by the scene when running CPxScene_simulate.
 	/// The buffer MUST be 16-byte aligned. If a buffer already exists then it is freed and a new one is allocated.