Convex Hull

Convex hull primitive. More...

Collaboration diagram for Convex Hull:

Data Structures
struct	b3HullVertex
	A hull vertex. More...
struct	b3HullHalfEdge
	Half-edge for hull data structure. More...
struct	b3HullFace
	A hull face. More...
struct	b3HullData
	A convex hull. More...
struct	b3BoxHull
	Efficient box hull. More...

Macros
#define	B3_HULL_VERSION   0x9D4716CE3793900Eull
	64-bit hull version. Useful for validating serialized data.

Functions
const b3HullVertex *	b3GetHullVertices (const b3HullData *hull)
	Get read only hull vertices.
const b3Vec3 *	b3GetHullPoints (const b3HullData *hull)
	Get read only hull points.
const b3HullHalfEdge *	b3GetHullEdges (const b3HullData *hull)
	Get read only hull half edges.
const b3HullFace *	b3GetHullFaces (const b3HullData *hull)
	Get read only hull faces.
const b3Plane *	b3GetHullPlanes (const b3HullData *hull)
	Get read only hull planes.
b3HullData *	b3CreateCylinder (float height, float radius, float yOffset, int sides)
	Create a tessellated cylinder as a hull.
b3HullData *	b3CreateCone (float height, float radius1, float radius2, int slices)
	Create a tessellated cone as a hull.
b3HullData *	b3CreateRock (float radius)
	Create a rock shaped hull.
b3HullData *	b3CreateHull (const b3Vec3 *points, int pointCount, int maxVertexCount)
	Create a generic convex hull.
b3HullData *	b3CloneHull (const b3HullData *hull)
	Deep clone a hull.
b3HullData *	b3CloneAndTransformHull (const b3HullData *original, b3Transform transform, b3Vec3 scale)
	Clone and transform a hull. Supports non-uniform and mirroring scale.
void	b3DestroyHull (b3HullData *hull)
	Destroy a hull.
b3BoxHull	b3MakeCubeHull (float halfWidth)
	Make a cube as a hull. Do not call b3DestroyHull on this.
b3BoxHull	b3MakeBoxHull (float hx, float hy, float hz)
	Make a box as a hull. Do not call b3DestroyHull on this.
b3BoxHull	b3MakeOffsetBoxHull (float hx, float hy, float hz, b3Vec3 offset)
	Make an offset box as a hull. Do not call b3DestroyHull on this.
b3BoxHull	b3MakeTransformedBoxHull (float hx, float hy, float hz, b3Transform transform)
	Make a transformed box as a hull.
b3BoxHull	b3MakeScaledBoxHull (b3Vec3 halfWidths, b3Transform transform, b3Vec3 postScale)
	This makes a transformed box hull with post scaling.
void	b3ScaleBox (b3Vec3 *halfWidths, b3Transform *transform, b3Vec3 postScale, float minHalfWidth)
	This takes a box with a transform and post scale and converts it into a box with the post scale resolved with new half-widths and transform.

Detailed Description

Convex hull primitive.

---

Data Structure Documentation

b3HullVertex

struct b3HullVertex

A hull vertex.

Identified by a half-edge with this vertex as its tail.

Data Fields
uint8_t	edge	A half-edge that has this vertex as the origin Can be used along with edge twins and winding order to traverse all the edges connected to this vertex.

b3HullHalfEdge

struct b3HullHalfEdge

Half-edge for hull data structure.

Data Fields
uint8_t	face	Face to the left of this edge.
uint8_t	next	Next edge index CCW.
uint8_t	origin	index of origin vertex and point
uint8_t	twin	Twin edge index.

b3HullFace

struct b3HullFace

A hull face.

Hulls use a half-edge data structure, so a face can be determined from a single half-edge index.

Data Fields
uint8_t	edge	An arbitrary half-edge on this face.

b3HullData

struct b3HullData

A convex hull.

Note

This data structure has data hanging off the end and cannot be directly copied.

Collaboration diagram for b3HullData:

Data Fields
b3AABB	aabb	Axis-aligned box in local space.
int	byteCount	The total number of bytes for this hull.
b3Vec3	center	The local centroid.
b3Matrix3	centralInertia	The inertia tensor about the centroid.
int	edgeCount	This is the half-edge count (double the edge count).
int	edgeOffset	Offset of the edge array in bytes from the struct address.
int	faceCount	The face count. Hulls faces are convex polygons.
int	faceOffset	Offset of the face array in bytes from the struct address.
uint32_t	hash	Hash of this hull (this field is zero when the hash is computed).
float	innerRadius	The radius of the largest sphere at the center.
int	padding	Explicit padding. Hull identity is a content hash and memcmp over raw bytes, so there must be no unnamed padding for struct copies to scramble.
int	planeOffset	Offset of the face plane array in bytes from the struct address.
int	pointOffset	Offset of the point array in bytes from the struct address.
float	surfaceArea	Surface area, typically in squared meters.
uint64_t	version	Version must be first and match B3_HULL_VERSION.
int	vertexCount	The vertex count.
int	vertexOffset	Offset of the vertex array in bytes from the struct address.
float	volume	Volume, typically in m^3.

b3BoxHull

struct b3BoxHull

Efficient box hull.

Collaboration diagram for b3BoxHull:

Data Fields
b3HullData	base	The embedded hull. So the offsets index into the arrays that follow.
b3HullHalfEdge	boxEdges[24]	Box half-edges.
b3HullFace	boxFaces[6]	Box faces.
b3Plane	boxPlanes[6]	Box face planes.
b3Vec3	boxPoints[8]	Box points.
b3HullVertex	boxVertices[8]	Box vertices.
uint8_t	padding[2]	Explicit padding, see b3HullData::padding.

Function Documentation

b3MakeScaledBoxHull()

b3BoxHull b3MakeScaledBoxHull	(	b3Vec3	halfWidths,
		b3Transform	transform,
		b3Vec3	postScale )

This makes a transformed box hull with post scaling.

This is useful for boxes that are scaled in a level editor. Such scaling can have reflection and shear. In the case of shear the result may be approximate. If you need to support shear consider using b3CreateHull. Do not call b3DestroyHull on this.

Parameters

halfWidths	positive half widths
transform	local transform of box
postScale	scale applied after the transform, may be negative

b3MakeTransformedBoxHull()

b3BoxHull b3MakeTransformedBoxHull	(	float	hx,
		float	hy,
		float	hz,
		b3Transform	transform )

Make a transformed box as a hull.

Do not call b3DestroyHull on this.

Parameters

hx,hy,hz	positive half widths
transform	local transform of box

b3ScaleBox()

void b3ScaleBox	(	b3Vec3 *	halfWidths,
		b3Transform *	transform,
		b3Vec3	postScale,
		float	minHalfWidth )

This takes a box with a transform and post scale and converts it into a box with the post scale resolved with new half-widths and transform.

This accepts non-uniform and negative scale. This is approximate if there is shear.

Parameters

halfWidths	[in/out] the box half widths
transform	[in/out] the box transform with rotation and translation
postScale	the post scale being applied to the box after the transform
minHalfWidth	the minimum half width after scale is applied