#include <soft2d/soft2d.h>

Classes
struct	S2Vec2

struct	S2Vec2I

struct	S2Material

struct	S2Kinematics

struct	S2BoxShape

struct	S2CircleShape

struct	S2EllipseShape

struct	S2CapsuleShape

struct	S2PolygonShape

union	S2ShapeUnion

struct	S2Shape

struct	S2Particle

struct	S2CollisionParameter

struct	S2WorldConfig
	Structure `S2WorldConfig` More...

Macros
#define	S2_VERSION 2001

#define	S2_FALSE 0

#define	S2_TRUE 1

#define	S2_NULL_HANDLE 0

Typedefs
typedef uint32_t	S2Bool

typedef uint32_t	S2Flags

typedef struct S2World_t *	S2World

typedef struct S2Body_t *	S2Body

typedef struct S2Collider_t *	S2Collider

typedef struct S2Trigger_t *	S2Trigger

typedef struct S2Vec2	S2Vec2

typedef struct S2Vec2I	S2Vec2I

typedef enum S2MaterialType	S2MaterialType

typedef struct S2Material	S2Material

typedef enum S2Mobility	S2Mobility

typedef struct S2Kinematics	S2Kinematics

typedef enum S2ShapeType	S2ShapeType

typedef struct S2BoxShape	S2BoxShape

typedef struct S2CircleShape	S2CircleShape

typedef struct S2EllipseShape	S2EllipseShape

typedef struct S2CapsuleShape	S2CapsuleShape

typedef struct S2PolygonShape	S2PolygonShape

typedef union S2ShapeUnion	S2ShapeUnion

typedef struct S2Shape	S2Shape

typedef struct S2Particle	S2Particle

typedef enum S2OutWorldBoundaryPolicy	S2OutWorldBoundaryPolicy

typedef enum S2CollisionType	S2CollisionType

typedef struct S2CollisionParameter	S2CollisionParameter

typedef struct S2WorldConfig	S2WorldConfig
	Structure `S2WorldConfig`

typedef void(*	S2ParticleManipulationCallback) (S2Particle *particles, uint32_t size)

typedef enum S2BufferName	S2BufferName

Enumerations
enum	S2MaterialType { S2_MATERIAL_TYPE_FLUID = 0 , S2_MATERIAL_TYPE_ELASTIC = 1 , S2_MATERIAL_TYPE_SNOW = 2 , S2_MATERIAL_TYPE_SAND = 3 , S2_MATERIAL_TYPE_MAX_ENUM = 0xffffffff }

enum	S2Mobility { S2_MOBILITY_STATIC = 0 , S2_MOBILITY_KINEMATIC = 1 , S2_MOBILITY_DYNAMIC = 2 , S2_MOBILITY_MAX_ENUM = 0xffffffff }

enum	S2ShapeType { S2_SHAPE_TYPE_BOX = 0 , S2_SHAPE_TYPE_CIRCLE = 1 , S2_SHAPE_TYPE_ELLIPSE = 2 , S2_SHAPE_TYPE_CAPSULE = 3 , S2_SHAPE_TYPE_POLYGON = 4 , S2_SHAPE_TYPE_MAX_ENUM = 0xffffffff }

enum	S2OutWorldBoundaryPolicy { S2_OUT_WORLD_BOUNDARY_POLICY_DEACTIVATION = 0 , S2_OUT_WORLD_BOUNDARY_POLICY_REMOVING = 1 , S2_OUT_WORLD_BOUNDARY_POLICY_MAX_ENUM = 0xffffffff }

enum	S2CollisionType { S2_COLLISION_TYPE_STICKY = 0 , S2_COLLISION_TYPE_SLIP = 1 , S2_COLLISION_TYPE_SEPARATE = 2 , S2_COLLISION_TYPE_MAX_ENUM = 0xffffffff }

enum	S2BufferName { S2_BUFFER_NAME_PARTICLE_NUM = 0 , S2_BUFFER_NAME_PARTICLE_POSITION = 1 , S2_BUFFER_NAME_PARTICLE_VELOCITY = 2 , S2_BUFFER_NAME_PARTICLE_TAG = 3 , S2_BUFFER_NAME_PARTICLE_ID = 4 , S2_BUFFER_NAME_FINE_GRID_COLLIDER_NUM = 5 , S2_BUFFER_NAME_FINE_GRID_TRIGGER_ID = 6 , S2_BUFFER_NAME_ELEMENT_INDICES = 7 , S2_BUFFER_NAME_MAX_ENUM = 0xffffffff }

Functions
S2_API S2World S2_API_CALL	s2_create_world (TiArch arch, TiRuntime runtime, const S2WorldConfig *config)

S2_API void S2_API_CALL	s2_destroy_world (S2World world)

S2_API S2Body S2_API_CALL	s2_create_body (S2World world, const S2Material material, const S2Kinematics kinematics, const S2Shape *shape, uint32_t tag)

S2_API S2Body S2_API_CALL	s2_create_custom_body (S2World world, const S2Material material, const S2Kinematics kinematics, uint32_t particle_num, void *particles_in_local_space, uint32_t tag)

S2_API S2Body S2_API_CALL	s2_create_mesh_body (S2World world, const S2Material material, const S2Kinematics kinematics, uint32_t particle_num, void particles_in_local_space, uint32_t index_num, void indices, uint32_t tag)

S2_API void S2_API_CALL	s2_destroy_body (S2Body body)

S2_API S2Collider S2_API_CALL	s2_create_collider (S2World world, const S2Kinematics kinematics, const S2Shape shape, const S2CollisionParameter *collision_parameter)

S2_API void S2_API_CALL	s2_destroy_collider (S2Collider collider)

S2_API S2Trigger S2_API_CALL	s2_create_trigger (S2World world, const S2Kinematics kinematics, const S2Shape shape)

S2_API void S2_API_CALL	s2_destroy_trigger (S2Trigger trigger)

S2_API void S2_API_CALL	s2_step (S2World world, float delta_time)

S2_API S2WorldConfig S2_API_CALL	s2_get_world_config (S2World world)

S2_API S2Vec2I S2_API_CALL	s2_get_world_grid_resolution (S2World world)

S2_API void S2_API_CALL	s2_set_substep_timestep (S2World world, float delta_time)

S2_API void S2_API_CALL	s2_set_gravity (S2World world, const S2Vec2 *gravity)

S2_API void S2_API_CALL	s2_set_world_query_enabled (S2World world, uint32_t enable)

S2_API void S2_API_CALL	s2_set_world_offset (S2World world, const S2Vec2 *offset)

S2_API void S2_API_CALL	s2_set_world_extent (S2World world, const S2Vec2 *extent)

S2_API void S2_API_CALL	s2_set_mesh_body_force_scale (S2World world, float scale)

S2_API void S2_API_CALL	s2_apply_impulse_in_circular_area (S2World world, const S2Vec2 impulse, const S2Vec2 center, float radius)

S2_API void S2_API_CALL	s2_get_buffer (S2World world, S2BufferName buffer_name, TiNdArray *buffer)

S2_API void S2_API_CALL	s2_export_buffer_to_texture (S2World world, S2BufferName buffer_name, S2Bool y_flipped, float scale, const TiTexture *texture)

S2_API void S2_API_CALL	s2_apply_linear_impulse (S2Body body, const S2Vec2 *impulse)

S2_API void S2_API_CALL	s2_apply_angular_impulse (S2Body body, float impulse)

S2_API void S2_API_CALL	s2_set_body_material (S2Body body, const S2Material *material)

S2_API void S2_API_CALL	s2_set_body_tag (S2Body body, uint32_t tag)

S2_API void S2_API_CALL	s2_set_collider_position (S2Collider collider, const S2Vec2 *position)

S2_API S2Vec2 S2_API_CALL	s2_get_collider_position (S2Collider collider)

S2_API void S2_API_CALL	s2_set_collider_rotation (S2Collider collider, float rotation)

S2_API float S2_API_CALL	s2_get_collider_rotation (S2Collider collider)

S2_API void S2_API_CALL	s2_set_collider_linear_velocity (S2Collider collider, const S2Vec2 *linear_velocity)

S2_API S2Vec2 S2_API_CALL	s2_get_collider_linear_velocity (S2Collider collider)

S2_API void S2_API_CALL	s2_set_collider_angular_velocity (S2Collider collider, float angular_velocity)

S2_API float S2_API_CALL	s2_get_collider_angular_velocity (S2Collider collider)

S2_API void S2_API_CALL	s2_set_trigger_position (S2Trigger trigger, const S2Vec2 *position)

S2_API S2Vec2 S2_API_CALL	s2_get_trigger_position (S2Trigger trigger)

S2_API void S2_API_CALL	s2_set_trigger_rotation (S2Trigger trigger, float rotation)

S2_API float S2_API_CALL	s2_get_trigger_rotation (S2Trigger trigger)

S2_API uint32_t S2_API_CALL	s2_query_trigger_overlapped (S2Trigger trigger)

S2_API uint32_t S2_API_CALL	s2_query_trigger_overlapped_by_tag (S2Trigger trigger, uint32_t tag, uint32_t mask)

S2_API uint32_t S2_API_CALL	s2_query_particle_num_in_trigger (S2Trigger trigger)

S2_API uint32_t S2_API_CALL	s2_query_particle_num_in_trigger_by_tag (S2Trigger trigger, uint32_t tag, uint32_t mask)

S2_API void S2_API_CALL	s2_remove_particles_in_trigger (S2Trigger trigger)

S2_API void S2_API_CALL	s2_remove_particles_in_trigger_by_tag (S2Trigger trigger, uint32_t tag, uint32_t mask)

S2_API void S2_API_CALL	s2_manipulate_particles_in_trigger (S2Trigger trigger, S2ParticleManipulationCallback callback)

Detailed Description

Soft2D utilizes Taichi C-API, some soft2d interfaces require taichi c-api types such as TiArch, TiRuntime, TiNdarray. Thus, the Taichi C-API header should be included before the soft2d header in practical coding. The documentation of Taichi C-API could be found at Taichi C-API Documentation.

Unless specified otherwise, physical quantity units in soft2d follow the international standard. For instance, length-related parameters should be given in 'meter', velocity-related parameters in 'meters per second'.

Macro Definition Documentation

◆ S2_FALSE

#define S2_FALSE 0

Definition S2_FALSE

A condition or a predicate is not satisfied; a statement is invalid.

◆ S2_NULL_HANDLE

#define S2_NULL_HANDLE 0

Definition S2_NULL_HANDLE

A sentinel invalid handle that will never be produced from a valid call to Soft2D C-API.

◆ S2_TRUE

#define S2_TRUE 1

Definition S2_TRUE

A condition or a predicate is satisfied; a statement is valid.

Typedef Documentation

◆ S2Body

typedef struct S2Body_t* S2Body

Handle S2Body

A body is a continuum to be simulated, which is composed of a group of particles. A body has properties such as center, mobility, material, etc.

◆ S2Bool

typedef uint32_t S2Bool

Alias S2Bool

A boolean value. Can be either `S2_TRUE` or `S2_FALSE`. Assignment with other values could lead to undefined behavior.

◆ S2BoxShape

typedef struct S2BoxShape S2BoxShape

Structure S2BoxShape

A box shape.

◆ S2BufferName

typedef enum S2BufferName S2BufferName

Enumeration S2BufferName

The names of soft2d's internal buffer, mainly used in s2_get_buffer(). Soft2D exposes a series of internal GPU buffers, the subsequent table shows the detailed descriptions of each buffer.

Buffer Name	Element Data Type	Dimension	Shape	Flatten size (in bytes)
particle_num	int	1	1	1*sizeof(int)
particle_position	float2	1	P	P2sizeof(float)
particle_velocity	float2	1	P	P2sizeof(float)
particle_tag	int	1	P	P*sizeof(int)
particle_id	int	1	P	P*sizeof(int)
fine_grid_collider_num	int	2	(FG.x, FG.y)	FG.xFG.ysizeof(int)
fine_grid_trigger_id	int	2	(FG.x, FG.y)	FG.xFG.ysizeof(int)
element_indices	int	1	E	E3sizeof(int)

P: Number of particles.
E: Number of triangle elements.
(FG.x, FG.y): Resolution of the fine grid.

◆ S2CapsuleShape

typedef struct S2CapsuleShape S2CapsuleShape

Structure S2CapsuleShape

A capsule shape. The default pose is lying along the x-axis.

◆ S2CircleShape

typedef struct S2CircleShape S2CircleShape

Structure S2CircleShape

A circle shape.

◆ S2Collider

typedef struct S2Collider_t* S2Collider

Handle S2Collider

A collider is an obstacle within the world that blocks the motion of bodies.

◆ S2CollisionParameter

typedef struct S2CollisionParameter S2CollisionParameter

Structure S2CollisionParameter

Colliders' collision parameters. Indicates a particle's behavior when colliding with the collider.

◆ S2CollisionType

typedef enum S2CollisionType S2CollisionType

Enumeration S2CollisionType

Colliders' collision types. Specifies a particle's behavior when colliding with a collider.

◆ S2EllipseShape

typedef struct S2EllipseShape S2EllipseShape

Structure S2EllipseShape

An ellipse shape.

◆ S2Flags

typedef uint32_t S2Flags

Alias S2Flags

A bit field that can be used to represent 32 orthogonal flags. Bits unspecified in the corresponding flag enum are ignored.

Enumerations and bit-field flags in the C-API have a S2_XXX_MAX_ENUM case to ensure the enum has a 32-bit range and in-memory size. It has no semantical impact and can be safely ignored.

◆ S2Kinematics

typedef struct S2Kinematics S2Kinematics

Structure S2Kinematics

The kinematic properties of an object (S2Body, S2Collider, or S2Trigger).

Since a body often contains multiple particles, every particle has its own kinematic state during the simulation. Thus, when creating a body, the specified S2Kinematics parameter is only meaningful for body initialization as the initial kinematic state of the body. A body's kinematics value becomes meaningless once the simulation starts.

◆ S2Material

typedef struct S2Material S2Material

Structure S2Material

Physical Materials. Describing a body's physical properties. This must be provided when creating a body.

◆ S2MaterialType

typedef enum S2MaterialType S2MaterialType

Enumeration S2MaterialType

Types of physical materials.

◆ S2Mobility

typedef enum S2Mobility S2Mobility

Enumeration S2Mobility

The mobility of an object (S2Body, S2Collider, or S2Trigger).

Bodies currently support S2_MOBILITY_STATIC and S2_MOBILITY_DYNAMIC mobilities.
Colliders currently support S2_MOBILITY_STATIC and S2_MOBILITY_KINEMATIC mobilities.
Triggers only support S2_MOBILITY_STATIC mobility.

◆ S2OutWorldBoundaryPolicy

typedef enum S2OutWorldBoundaryPolicy S2OutWorldBoundaryPolicy

Enumeration S2OutWorldBoundaryPolicy

This policy specifies the behavior of a body when it leaves the world.

◆ S2Particle

typedef struct S2Particle S2Particle

Structure S2Particle

Represents a particle in soft2d. Users could access particle attributes via this structure. This structure is primarily used in s2_manipulate_particles_in_trigger().

◆ S2ParticleManipulationCallback

typedef void(* S2ParticleManipulationCallback) ( S2Particle *particles, uint32_t size)

FunctionPointerType S2ParticleManipulationCallback

A function pointer type. The function pointer type is primarily used in s2_manipulate_particles_in_trigger().

Parameters

particles	A particle buffer provided by soft2d.
size	The number of particles within the particle buffer.

Parameters

particles	A particle buffer provided by soft2d.
size	The number of particles within the particle buffer.

◆ S2PolygonShape

typedef struct S2PolygonShape S2PolygonShape

Structure S2PolygonShape

A polygon shape. A polygon shape requires users to provide a pointer of S2Vec2 C array which stores all vertices of a polygon. These vertices should be in a counter-clockwise order.

◆ S2Shape

typedef struct S2Shape S2Shape

Structure S2Shape

A uniform representation of various shape structures. The value of type should be consistent with the underlying shape structure of shape_union.

◆ S2ShapeType

typedef enum S2ShapeType S2ShapeType

Enumeration S2ShapeType

Types of predefined shapes.

◆ S2ShapeUnion

typedef union S2ShapeUnion S2ShapeUnion

Union S2ShapeUnion

A union of shape structures, designed for a uniform representation of various shape structures.

◆ S2Trigger

typedef struct S2Trigger_t* S2Trigger

Handle S2Trigger

A trigger is a spatial area with a specific shape, which is able to detect particles passing through it.

◆ S2Vec2

typedef struct S2Vec2 S2Vec2

Structure S2Vec2

A 2D floating-point vector type.

◆ S2Vec2I

typedef struct S2Vec2I S2Vec2I

Structure S2Vec2I

A 2D integer vector type.

◆ S2World

typedef struct S2World_t* S2World

Handle S2World

A world is a container that contains all simulation-related objects within a scene and simulates them over time under physical laws.

Enumeration Type Documentation

◆ S2BufferName

enum S2BufferName

Enumeration S2BufferName

The names of soft2d's internal buffer, mainly used in s2_get_buffer(). Soft2D exposes a series of internal GPU buffers, the subsequent table shows the detailed descriptions of each buffer.

Buffer Name	Element Data Type	Dimension	Shape	Flatten size (in bytes)
particle_num	int	1	1	1*sizeof(int)
particle_position	float2	1	P	P2sizeof(float)
particle_velocity	float2	1	P	P2sizeof(float)
particle_tag	int	1	P	P*sizeof(int)
particle_id	int	1	P	P*sizeof(int)
fine_grid_collider_num	int	2	(FG.x, FG.y)	FG.xFG.ysizeof(int)
fine_grid_trigger_id	int	2	(FG.x, FG.y)	FG.xFG.ysizeof(int)
element_indices	int	1	E	E3sizeof(int)

P: Number of particles.
E: Number of triangle elements.
(FG.x, FG.y): Resolution of the fine grid.

Enumerator
S2_BUFFER_NAME_PARTICLE_NUM	This buffer only stores a single float value, indicating the current number of particles in the world.
S2_BUFFER_NAME_PARTICLE_POSITION	Stores positions of all particles.
S2_BUFFER_NAME_PARTICLE_VELOCITY	Stores velocities of all particles.
S2_BUFFER_NAME_PARTICLE_TAG	Stores tags of all particles.
S2_BUFFER_NAME_PARTICLE_ID	Stores IDs of all particles.
S2_BUFFER_NAME_FINE_GRID_COLLIDER_NUM	Stores the number of colliders at every cell of the fine grid (after discretization). This buffer can be exported only if `S2WorldConfig.enable_debugging` is true.
S2_BUFFER_NAME_FINE_GRID_TRIGGER_ID	Stores the trigger's ID (0 if none) at every cell of the fine grid (after discretization). If multiple triggers overlap on a single cell, only the ID of the most recently added trigger is stored. This buffer can be exported only if `S2WorldConfig.enable_debugging` is true.
S2_BUFFER_NAME_ELEMENT_INDICES	Stores all indices of particles of all triangle elements. Note this index means the particle's index in the particle buffer, instead of their ID.

◆ S2CollisionType

enum S2CollisionType

Enumeration S2CollisionType

Colliders' collision types. Specifies a particle's behavior when colliding with a collider.

Enumerator
S2_COLLISION_TYPE_STICKY	All velocity components of the particle will be set to 0.
S2_COLLISION_TYPE_SLIP	The particle's velocity component along the contact normal direction will be set to 0, which leads to the particle 'sliding' along the collider surface. With this type, users can modify `S2CollisionParameter.friction_coeff` to adjust the friction to control the particle's behavior.
S2_COLLISION_TYPE_SEPARATE	If the particle's velocity component along the contact normal direction is negative, then this part of the component will be set to 0. Otherwise, it keeps its original velocity. With this type, users can modify `S2CollisionParameter.friction_coeff` and `S2CollisionParameter.restitution_coeff` to adjust the friction and restitution to control the particle's behavior.

◆ S2MaterialType

enum S2MaterialType

Enumeration S2MaterialType

Types of physical materials.

Enumerator
S2_MATERIAL_TYPE_FLUID	Fluid type.
S2_MATERIAL_TYPE_ELASTIC	Elastic body type.
S2_MATERIAL_TYPE_SNOW	Snow type.
S2_MATERIAL_TYPE_SAND	Sand type.

◆ S2Mobility

enum S2Mobility

Enumeration S2Mobility

The mobility of an object (S2Body, S2Collider, or S2Trigger).

Bodies currently support S2_MOBILITY_STATIC and S2_MOBILITY_DYNAMIC mobilities.
Colliders currently support S2_MOBILITY_STATIC and S2_MOBILITY_KINEMATIC mobilities.
Triggers only support S2_MOBILITY_STATIC mobility.

Enumerator
S2_MOBILITY_STATIC	A static object's velocity is zero and its position can not be changed throughout the simulation.
S2_MOBILITY_KINEMATIC	A kinematic object is able to move, but it would not 'collide' with other objects.
S2_MOBILITY_DYNAMIC	A dynamic object is able to move, and it is able to 'collide' with other objects.

◆ S2OutWorldBoundaryPolicy

enum S2OutWorldBoundaryPolicy

Enumeration S2OutWorldBoundaryPolicy

This policy specifies the behavior of a body when it leaves the world.

Enumerator
S2_OUT_WORLD_BOUNDARY_POLICY_DEACTIVATION	The body will still exist in the world, but it will be deactivated. This body won't move or interact with other objects anymore.
S2_OUT_WORLD_BOUNDARY_POLICY_REMOVING	All particles in this body will be removed from the world (leading to an empty body).

◆ S2ShapeType

enum S2ShapeType

Enumeration S2ShapeType

Types of predefined shapes.

Enumerator
S2_SHAPE_TYPE_BOX	Box type.
S2_SHAPE_TYPE_CIRCLE	Circle type.
S2_SHAPE_TYPE_ELLIPSE	Ellipse type.
S2_SHAPE_TYPE_CAPSULE	Capsule type.
S2_SHAPE_TYPE_POLYGON	Polygon type.

Function Documentation

◆ s2_apply_angular_impulse()

S2_API void S2_API_CALL s2_apply_angular_impulse	(	S2Body	body,
		float	impulse
	)

Function s2_apply_angular_impulse

Apply an angular impulse to all particles within a body. The average value of positions of all particles is treated as the body's center.

Parameters

body	Body handle.
impulse	Applied angular impulse.

◆ s2_apply_impulse_in_circular_area()

S2_API void S2_API_CALL s2_apply_impulse_in_circular_area	(	S2World	world,
		const S2Vec2 *	impulse,
		const S2Vec2 *	center,
		float	radius
	)

Function s2_apply_impulse_in_circular_area

Apply an impulse within a specified circular spatial region.

Parameters

world	World handle.
impulse	Applied impulse, equivalent to applied_force * applied_time.
center	The center of the specified circular area.
radius	The radius of the specified circular area.

◆ s2_apply_linear_impulse()

S2_API void S2_API_CALL s2_apply_linear_impulse	(	S2Body	body,
		const S2Vec2 *	impulse
	)

Function s2_apply_linear_impulse

Apply a linear impulse to all particles within a body.

Parameters

body	Body handle.
impulse	Applied linear impulse.

◆ s2_create_body()

S2_API S2Body S2_API_CALL s2_create_body	(	S2World	world,
		const S2Material *	material,
		const S2Kinematics *	kinematics,
		const S2Shape *	shape,
		uint32_t	tag
	)

Function s2_create_body

Create a body with a predefined shape. Soft2D automatically generates the particles within the body.

Parameters

world	World handle.
material	Body's physical material.
kinematics	Body's kinematic properties.
shape	Body' shape.
tag	User-specified custom tag.

◆ s2_create_collider()

S2_API S2Collider S2_API_CALL s2_create_collider	(	S2World	world,
		const S2Kinematics *	kinematics,
		const S2Shape *	shape,
		const S2CollisionParameter *	collision_parameter
	)

Function s2_create_collider

Create a collider with specified parameters.

Parameters

world	World handle.
kinematics	Collider's kinematic properties.
shape	Collider's shape.
collision_parameter	Collider's collision parameters.

◆ s2_create_custom_body()

S2_API S2Body S2_API_CALL s2_create_custom_body	(	S2World	world,
		const S2Material *	material,
		const S2Kinematics *	kinematics,
		uint32_t	particle_num,
		void *	particles_in_local_space,
		uint32_t	tag
	)

Function s2_create_custom_body

Create a body with user-specified particles. These particles form a complete body and their locations should be provided in the body's local space.

Parameters

world	World handle.
material	Body's physical material.
kinematics	Body's kinematic properties.
particle_num	The number of particles in the `particles_in_local_space` buffer.
particles_in_local_space	User-specified particles data. This should be provided as a pointer of C S2Vec2 array. This array stores the local positions of all particles.
tag	User-specified custom tag.

◆ s2_create_mesh_body()

S2_API S2Body S2_API_CALL s2_create_mesh_body	(	S2World	world,
		const S2Material *	material,
		const S2Kinematics *	kinematics,
		uint32_t	particle_num,
		void *	particles_in_local_space,
		uint32_t	index_num,
		void *	indices,
		uint32_t	tag
	)

Function s2_create_mesh_body

Create a body with a 2D triangle mesh. The indices' winding order should be counter-clockwise.

Parameters

world	World handle.
material	Body's physical material.
kinematics	Body's kinematic properties.
particle_num	The number of vertices in the `particles_in_local_space` buffer.
particles_in_local_space	The mesh's vertices data. This should be provided as a pointer of C S2Vec2 array. This array stores the local positions of all particles.
index_num	The number of indices in the `indices` buffer.
indices	The mesh's indices data. This should be provided as a pointer of C `int` array. This array stores the indices of all triangle elements. Indices for a triangle element should be in a counter-clockwise winding order.
tag	User-specified custom tag.

◆ s2_create_trigger()

S2_API S2Trigger S2_API_CALL s2_create_trigger	(	S2World	world,
		const S2Kinematics *	kinematics,
		const S2Shape *	shape
	)

Function s2_create_trigger

Create a trigger with specified parameters.

Parameters

world	World handle.
kinematics	Trigger's kinematic properties.
shape	Trigger's shape.

◆ s2_create_world()

S2_API S2World S2_API_CALL s2_create_world	(	TiArch	arch,
		TiRuntime	runtime,
		const S2WorldConfig *	config
	)

Function s2_create_world

Create a world with specified parameters.

Parameters

arch	Architecture of the taichi runtime.
runtime	An instance of the taichi runtime.
config	World's configuration.

◆ s2_destroy_body()

S2_API void S2_API_CALL s2_destroy_body ( S2Body body )

Function s2_destroy_body

Remove a body from the world and destroy it.

Parameters

body	The body to be destroyed.

◆ s2_destroy_collider()

S2_API void S2_API_CALL s2_destroy_collider ( S2Collider collider )

Function s2_destroy_collider

Remove a collider from the world and destroy it.

Parameters

collider The collider to be destroyed.

◆ s2_destroy_trigger()

S2_API void S2_API_CALL s2_destroy_trigger ( S2Trigger trigger )

Function s2_destroy_trigger

Remove a trigger from the world and destroy it.

Parameters

trigger The trigger to be destroyed.

◆ s2_destroy_world()

S2_API void S2_API_CALL s2_destroy_world ( S2World world )

Function s2_destroy_world

Destroy a world.

Parameters

world The world to be destroyed.

◆ s2_export_buffer_to_texture()

S2_API void S2_API_CALL s2_export_buffer_to_texture	(	S2World	world,
		S2BufferName	buffer_name,
		S2Bool	y_flipped,
		float	scale,
		const TiTexture *	texture
	)

Function s2_export_buffer_to_texture

Export buffer data to a user-specified texture, useful for rendering or debugging. Currently, this function only support S2_BUFFER_NAME_FINE_GRID_COLLIDER_NUM and S2_BUFFER_NAME_FINE_GRID_COLLIDER_NUM.

Parameters

world	World handle.
buffer_name	The buffer name to export. Currently, this arguments only supports S2_BUFFER_NAME_FINE_GRID_COLLIDER_NUM or S2_BUFFER_NAME_FINE_GRID_COLLIDER_NUM.
y_flipped	A option to control whether flip the coordinates of the y-axis or not.
scale	A factor to scale the numerical data to be exported.
texture	The destination texture for exporting.

◆ s2_get_buffer()

S2_API void S2_API_CALL s2_get_buffer	(	S2World	world,
		S2BufferName	buffer_name,
		TiNdArray *	buffer
	)

Function s2_get_buffer

Get the handle of a soft2d internal GPU buffer, useful for rendering or debugging.

Parameters

world	World handle.
buffer_name	The name of the internal buffer as per S2BufferName.
buffer	A pointer to a `TiNdArray` to store the internal buffer reference.

◆ s2_get_collider_angular_velocity()

S2_API float S2_API_CALL s2_get_collider_angular_velocity ( S2Collider collider )

Function s2_get_collider_angular_velocity

Get a collider's angular velocity.

Parameters

collider Collider handle.

◆ s2_get_collider_linear_velocity()

S2_API S2Vec2 S2_API_CALL s2_get_collider_linear_velocity ( S2Collider collider )

Function s2_get_collider_linear_velocity

Get a collider's linear velocity.

Parameters

collider Collider handle.

◆ s2_get_collider_position()

S2_API S2Vec2 S2_API_CALL s2_get_collider_position ( S2Collider collider )

Function s2_get_collider_position

Get a collider's position.

Parameters

collider Collider handle.

◆ s2_get_collider_rotation()

S2_API float S2_API_CALL s2_get_collider_rotation ( S2Collider collider )

Function s2_get_collider_rotation

Get a collider's rotation.

Parameters

collider Collider handle.

◆ s2_get_trigger_position()

S2_API S2Vec2 S2_API_CALL s2_get_trigger_position ( S2Trigger trigger )

Function s2_get_trigger_position

Get a trigger's position.

Parameters

trigger Trigger handle.

◆ s2_get_trigger_rotation()

S2_API float S2_API_CALL s2_get_trigger_rotation ( S2Trigger trigger )

Function s2_get_trigger_rotation

Get a trigger's rotation.

Parameters

trigger Trigger handle.

◆ s2_get_world_config()

S2_API S2WorldConfig S2_API_CALL s2_get_world_config ( S2World world )

Function s2_get_world_config

Get the current configuration of the specified world.

Parameters

world World handle.

◆ s2_get_world_grid_resolution()

S2_API S2Vec2I S2_API_CALL s2_get_world_grid_resolution ( S2World world )

Function s2_get_world_grid_resolution

Get the current 2D grid resolution of the world. The grid resolution value in WorldConfig is one single integer, indicating the maximum component of grid resolution along the x-axis and the y-axis. This function returns both two components of the grid resolution in S2Vec2I type.

Parameters

world World handle.

◆ s2_manipulate_particles_in_trigger()

S2_API void S2_API_CALL s2_manipulate_particles_in_trigger	(	S2Trigger	trigger,
		S2ParticleManipulationCallback	callback
	)

Function s2_manipulate_particles_in_trigger

Manipulate particles in a trigger area. An internal particle buffer is exposed to users via this function, and users could provide a callback function operating on that buffer. The user-provided callback function will be automatically executed before the next step. Currently, this function allows two kinds of users' operations:

Change the tag of a particle by modifying S2Particle.tag.
Mark a particle for removal before the next step by setting S2Particle.is_removed to true.

See S2Particle and S2ParticleManipulationCallback for more details. This function works only when S2WorldConfig.enable_world_query is true.

Parameters

trigger	Trigger handle.
callback	User-specified callback function. This parameter should be a function pointer of the S2ParticleManipulationCallback type.

◆ s2_query_particle_num_in_trigger()

S2_API uint32_t S2_API_CALL s2_query_particle_num_in_trigger ( S2Trigger trigger )

Function s2_query_particle_num_in_trigger

Query the number of particles in a trigger area. This function works only when S2WorldConfig.enable_world_query is true.

Parameters

trigger Trigger handle.

◆ s2_query_particle_num_in_trigger_by_tag()

S2_API uint32_t S2_API_CALL s2_query_particle_num_in_trigger_by_tag	(	S2Trigger	trigger,
		uint32_t	tag,
		uint32_t	mask
	)

Function s2_query_particle_num_in_trigger_by_tag

Query the number of specified particles in a trigger area. A particle is treated as specified only when it satisfies the condition: (particle.tag & mask) == tag. This function works only when S2WorldConfig.enable_world_query is true.

Parameters

trigger	Trigger handle.
tag	User-specified tag.
mask	User-specified mask.

◆ s2_query_trigger_overlapped()

S2_API uint32_t S2_API_CALL s2_query_trigger_overlapped ( S2Trigger trigger )

Function s2_query_trigger_overlapped

Query whether there are particles in a trigger area. This function works only when S2WorldConfig.enable_world_query is true.

Parameters

trigger Trigger handle.

◆ s2_query_trigger_overlapped_by_tag()

S2_API uint32_t S2_API_CALL s2_query_trigger_overlapped_by_tag	(	S2Trigger	trigger,
		uint32_t	tag,
		uint32_t	mask
	)

Function s2_query_trigger_overlapped_by_tag

Query whether there are specified particles in a trigger area. A particle is treated as specified only when it satisfies the condition: (particle.tag & mask) == tag. This function works only when S2WorldConfig.enable_world_query is true.

Parameters

trigger	Trigger handle.
tag	User-specified tag.
mask	User-specified mask.

◆ s2_remove_particles_in_trigger()

S2_API void S2_API_CALL s2_remove_particles_in_trigger ( S2Trigger trigger )

Function s2_remove_particles_in_trigger

Remove all particles in a trigger area from the world. This function works only when S2WorldConfig.enable_world_query is true.

Parameters

trigger Trigger handle.

◆ s2_remove_particles_in_trigger_by_tag()

S2_API void S2_API_CALL s2_remove_particles_in_trigger_by_tag	(	S2Trigger	trigger,
		uint32_t	tag,
		uint32_t	mask
	)

Function s2_remove_particles_in_trigger_by_tag

Remove all specified particles in a trigger area from the world. A particle is treated as specified only when it satisfies the condition: (particle.tag & mask) == tag. This function works only when S2WorldConfig.enable_world_query is true.

Parameters

trigger	Trigger handle.
tag	User-specified tag.
mask	User-specified mask.

◆ s2_set_body_material()

S2_API void S2_API_CALL s2_set_body_material	(	S2Body	body,
		const S2Material *	material
	)

Function s2_set_body_material

Set a body's physical material.

Parameters

body	Body handle.
material	The new value of material.

◆ s2_set_body_tag()

S2_API void S2_API_CALL s2_set_body_tag	(	S2Body	body,
		uint32_t	tag
	)

Function s2_set_body_tag

Set all particles' tags in a body to a single value.

Parameters

body	Body handle.
tag	The new value of tag.

◆ s2_set_collider_angular_velocity()

S2_API void S2_API_CALL s2_set_collider_angular_velocity	(	S2Collider	collider,
		float	angular_velocity
	)

Function s2_set_collider_angular_velocity

Set a collider's angular velocity.

Parameters

collider	Collider handle.
angular_velocity	The new value of angular velocity.

◆ s2_set_collider_linear_velocity()

S2_API void S2_API_CALL s2_set_collider_linear_velocity	(	S2Collider	collider,
		const S2Vec2 *	linear_velocity
	)

Function s2_set_collider_linear_velocity

Set a collider's linear velocity.

Parameters

collider	Collider handle.
linear_velocity	The new value of linear velocity.

◆ s2_set_collider_position()

S2_API void S2_API_CALL s2_set_collider_position	(	S2Collider	collider,
		const S2Vec2 *	position
	)

Function s2_set_collider_position

Set a collider's position.

Parameters

collider	Collider handle.
position	The new value of position.

◆ s2_set_collider_rotation()

S2_API void S2_API_CALL s2_set_collider_rotation	(	S2Collider	collider,
		float	rotation
	)

Function s2_set_collider_rotation

Set a collider's rotation.

Parameters

collider	Collider handle.
rotation	The new value of rotation.

◆ s2_set_gravity()

S2_API void S2_API_CALL s2_set_gravity	(	S2World	world,
		const S2Vec2 *	gravity
	)

Function s2_set_gravity

Set a world's gravity.

Parameters

world	World handle.
gravity	The new value of gravity.

◆ s2_set_mesh_body_force_scale()

S2_API void S2_API_CALL s2_set_mesh_body_force_scale	(	S2World	world,
		float	scale
	)

Function s2_set_mesh_body_force_scale

Set the scale factor of the mesh body's internal force.

Parameters

world	World handle.
scale	The new value of scale.

◆ s2_set_substep_timestep()

S2_API void S2_API_CALL s2_set_substep_timestep	(	S2World	world,
		float	delta_time
	)

Function s2_set_substep_timestep

Set the time step for simulation sub-steps.

Parameters

world	World handle.
delta_time	The new time step of each sub-step.

◆ s2_set_trigger_position()

S2_API void S2_API_CALL s2_set_trigger_position	(	S2Trigger	trigger,
		const S2Vec2 *	position
	)

Function s2_set_trigger_position

Set a trigger's position.

Parameters

trigger	Trigger handle.
position	The new value of position.

◆ s2_set_trigger_rotation()

S2_API void S2_API_CALL s2_set_trigger_rotation	(	S2Trigger	trigger,
		float	rotation
	)

Function s2_set_trigger_rotation

Set a trigger's rotation.

Parameters

trigger	Trigger handle.
rotation	The new value of rotation.

◆ s2_set_world_extent()

S2_API void S2_API_CALL s2_set_world_extent	(	S2World	world,
		const S2Vec2 *	extent
	)

Function s2_set_world_extent

Set a world's extent.

Parameters

world World handle.

◆ s2_set_world_offset()

S2_API void S2_API_CALL s2_set_world_offset	(	S2World	world,
		const S2Vec2 *	offset
	)

Function s2_set_world_offset

Set a world's offset.

Parameters

world World handle.

◆ s2_set_world_query_enabled()

S2_API void S2_API_CALL s2_set_world_query_enabled	(	S2World	world,
		uint32_t	enable
	)

Function s2_set_world_query_enabled

Enable or disable the world querying.

Parameters

world	World handle.
enable	A `S2Bool` value, indicating enabling or disabling.

◆ s2_step()

S2_API void S2_API_CALL s2_step	(	S2World	world,
		float	delta_time
	)

Function s2_step

Advance a world's simulation by a real-world time step.

Parameters

world	The world to be simulated.
delta_time	The time step for a step, indicating a real-world time duration.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ S2_FALSE

◆ S2_NULL_HANDLE

◆ S2_TRUE

Typedef Documentation

◆ S2Body

◆ S2Bool

◆ S2BoxShape

◆ S2BufferName

◆ S2CapsuleShape

◆ S2CircleShape

◆ S2Collider

◆ S2CollisionParameter

◆ S2CollisionType

◆ S2EllipseShape

◆ S2Flags

◆ S2Kinematics

◆ S2Material

◆ S2MaterialType

◆ S2Mobility

◆ S2OutWorldBoundaryPolicy

◆ S2Particle

◆ S2ParticleManipulationCallback

◆ S2PolygonShape

◆ S2Shape

◆ S2ShapeType

◆ S2ShapeUnion

◆ S2Trigger

◆ S2Vec2

◆ S2Vec2I

◆ S2World

Enumeration Type Documentation

◆ S2BufferName

◆ S2CollisionType

◆ S2MaterialType

◆ S2Mobility

◆ S2OutWorldBoundaryPolicy

◆ S2ShapeType

Function Documentation

◆ s2_apply_angular_impulse()

◆ s2_apply_impulse_in_circular_area()

◆ s2_apply_linear_impulse()

◆ s2_create_body()

◆ s2_create_collider()

◆ s2_create_custom_body()

◆ s2_create_mesh_body()

◆ s2_create_trigger()

◆ s2_create_world()

◆ s2_destroy_body()

◆ s2_destroy_collider()

◆ s2_destroy_trigger()

◆ s2_destroy_world()

◆ s2_export_buffer_to_texture()

◆ s2_get_buffer()

◆ s2_get_collider_angular_velocity()

◆ s2_get_collider_linear_velocity()

◆ s2_get_collider_position()

◆ s2_get_collider_rotation()

◆ s2_get_trigger_position()

◆ s2_get_trigger_rotation()

◆ s2_get_world_config()

◆ s2_get_world_grid_resolution()

◆ s2_manipulate_particles_in_trigger()

◆ s2_query_particle_num_in_trigger()

◆ s2_query_particle_num_in_trigger_by_tag()

◆ s2_query_trigger_overlapped()

◆ s2_query_trigger_overlapped_by_tag()

◆ s2_remove_particles_in_trigger()

◆ s2_remove_particles_in_trigger_by_tag()

◆ s2_set_body_material()

◆ s2_set_body_tag()

◆ s2_set_collider_angular_velocity()

◆ s2_set_collider_linear_velocity()

◆ s2_set_collider_position()