API for creating and running game of life simulations. More...

Data Structures
struct	gol_simulation_property_grid_access_profiling
	Statistics collected per frame about access to grid cells. More...

struct	gol_grid_position
	Position in 2D simulation grid. More...

struct	gol_cell
	Cell at certain position that can be either dead or alive. More...

Macros
#define	GOL_TRUE 1
	True value.

#define	GOL_FALSE 0
	False value.

Typedefs
typedef void *	gol_handle
	Generic opaque handle.

typedef gol_handle	gol_simulation
	Handle for simulation resource.

typedef int32_t	gol_grid_scalar
	Position in single grid dimension.

typedef int32_t	gol_bool
	Boolean type.

typedef uintptr_t	gol_size
	Type representing nonnegative size of collections.

typedef uint32_t	gol_simulation_property_frame_count
	Count of time steps processed by the simulation.

Enumerations
enum	gol_result { GOL_RESULT_SUCCESS = 0 , GOL_RESULT_ERROR = 1 , GOL_RESULT_UNKNOWN_SIMULATION_PROPERTY }
	Defines possible operation results. More...

enum	gol_simulation_property_type { GOL_SIMULATION_PROPERTY_TYPE_FRAME_COUNT , GOL_SIMULATION_PROPERTY_TYPE_GRID_ACCESS_PROFILING }
	Lists available simulation properties. More...

Functions
gol_result	gol_simulation_create (gol_simulation *simulation)
	Creates new simulation.

gol_result	gol_simulation_query_property (gol_simulation simulation, gol_simulation_property_type property, gol_size bytes, void data)
	Query simulation property.

gol_result	gol_simulation_next_frame (gol_simulation simulation)
	Progress simulation to next time step.

gol_result	gol_simulation_query_cells (gol_simulation simulation, gol_size size, const gol_grid_position positions, gol_cell cells)
	Query cells at multiple positions.

gol_result	gol_simulation_set_cells (gol_simulation simulation, gol_size size, const gol_cell *cells)
	Update multiple simulation cells.

gol_result	gol_simulation_get_alive_cells (gol_simulation simulation, gol_size size, gol_cell cells)
	Query all alive cells.

gol_result	gol_simulation_get_updated_cells (gol_simulation simulation, gol_size size, gol_cell cells)
	Query cells updated by the simulation in last time step.

gol_result	gol_simulation_destroy (gol_simulation simulation)
	Destroys existing simulation.

Detailed Description

API for creating and running game of life simulations.

Macro Definition Documentation

◆ GOL_FALSE

#define GOL_FALSE 0

False value.

Since: 1.0.0

◆ GOL_TRUE

#define GOL_TRUE 1

True value.

Since: 1.0.0

Typedef Documentation

◆ gol_bool

typedef int32_t gol_bool

Boolean type.

Since: 1.0.0

◆ gol_grid_scalar

typedef int32_t gol_grid_scalar

Position in single grid dimension.

Since: 1.0.0

◆ gol_handle

typedef void* gol_handle

Generic opaque handle.

Since: 1.0.0

◆ gol_simulation

typedef gol_handle gol_simulation

Handle for simulation resource.

Since: 1.0.0

◆ gol_simulation_property_frame_count

typedef uint32_t gol_simulation_property_frame_count

Count of time steps processed by the simulation.

Since: 1.0.0

◆ gol_size

typedef uintptr_t gol_size

Type representing nonnegative size of collections.

Since: 1.0.0

Enumeration Type Documentation

◆ gol_result

enum gol_result

Defines possible operation results.

Since: 1.0.0

Enumerator
GOL_RESULT_SUCCESS	Operation succeded.
GOL_RESULT_ERROR	Operation failed.
GOL_RESULT_UNKNOWN_SIMULATION_PROPERTY	Operation failed because of unknown simulation property.

◆ gol_simulation_property_type

enum gol_simulation_property_type

Lists available simulation properties.

Since: 1.0.0

Enumerator
GOL_SIMULATION_PROPERTY_TYPE_FRAME_COUNT	Property type for gol_simulation_property_frame_count.
GOL_SIMULATION_PROPERTY_TYPE_GRID_ACCESS_PROFILING	Property type for gol_simulation_property_grid_access_profiling

Function Documentation

◆ gol_simulation_create()

gol_result gol_simulation_create ( gol_simulation * simulation )

Creates new simulation.

Since: 1.0.0

Created simulation is empty - all cells are in dead state.
Application is responsible for destroying simulation with gol_simulation_destroy().
Application may call this function from simultaneus threads.

Parameters

[in,out] simulation Pointer for writing new simulation handle.

Return values

GOL_RESULT_SUCCESS Operation succeeded.

◆ gol_simulation_destroy()

gol_result gol_simulation_destroy ( gol_simulation simulation )

Destroys existing simulation.

Since: 1.0.0

All resources owned by the simulation are immediately released.
Application must not use simulation handle or resources after it was destroyed.
Simultaneus threads may call this function only with different simulation handles.

Parameters

[in] simulation Handle to destroy.

Return values

GOL_RESULT_SUCCESS Operation succeeded.

◆ gol_simulation_get_alive_cells()

gol_result gol_simulation_get_alive_cells	(	gol_simulation	simulation,
		gol_size *	size,
		gol_cell *	cells
	)

Query all alive cells.

Since: 1.0.0

This operation does not mutate simulation state.
Simultaneus threads may call this function with different simulation handles.
Simultaneus threads may call this and other functions that do not modify simulation state with the same simulation handle.

Parameters

[in]	simulation	Simulation to query.
[out]	size	Pointer for writing number of alive cells. Ignored if NULL.
[out]	cells	Pointer for writing alive cells. Ignored if NULL.

Return values

GOL_RESULT_SUCCESS Operation succeeded.

◆ gol_simulation_get_updated_cells()

gol_result gol_simulation_get_updated_cells	(	gol_simulation	simulation,
		gol_size *	size,
		gol_cell *	cells
	)

Query cells updated by the simulation in last time step.

Since: 1.0.0

This operation does not mutate simulation state.
Simultaneus threads may call this function with different simulation handles.
Simultaneus threads may call this and other functions that do not modify simulation state with the same simulation handle.

Parameters

[in]	simulation	Simulation to query.
[out]	size	Pointer for writing number of updated cells. Ignored if NULL.
[out]	cells	Pointer for writing updated cells. Ignored if NULL.

Return values

GOL_RESULT_SUCCESS Operation succeeded.

◆ gol_simulation_next_frame()

gol_result gol_simulation_next_frame ( gol_simulation simulation )

Progress simulation to next time step.

Since: 1.0.0

Simulation state is updated according to simulation rules.
This operation mutates simulation state.
Simultaneus threads may call this function only with different simulation handles.

Parameters

[in] simulation Simulation to progress.

Return values

GOL_RESULT_SUCCESS Operation succeeded.

◆ gol_simulation_query_cells()

gol_result gol_simulation_query_cells	(	gol_simulation	simulation,
		gol_size	size,
		const gol_grid_position *	positions,
		gol_cell *	cells
	)

Query cells at multiple positions.

Since: 1.0.0

This operation does not mutate simulation state.
Simultaneus threads may call this function with different simulation handles.
Simultaneus threads may call this and other functions that do not modify simulation state with the same simulation handle.

Parameters

[in]	simulation	Simulation to query.
[in]	size	Number of positions to query.
[in]	positions	Pointer for reading queried positions.
[out]	cells	Pointer for writing queried cells. Order of written cells corresponds to order of queried positions.

Return values

GOL_RESULT_SUCCESS Operation succeeded.

◆ gol_simulation_query_property()

gol_result gol_simulation_query_property	(	gol_simulation	simulation,
		gol_simulation_property_type	property,
		gol_size *	bytes,
		void *	data
	)

Query simulation property.

Since: 1.0.0

See gol_simulation_property_type for available properties.

This operation does not mutate simulation state.
Simultaneus threads may call this function with different simulation handles.
Simultaneus threads may call this and other functions that do not modify simulation state with the same simulation handle.

Parameters

[in]	simulation	Simulation to query.
[in]	property	Property to query.
[out]	bytes	Pointer for writing size of query results in bytes. Ignored if NULL.
[out]	data	Pointer for writing query results. Ignored if NULL.

Return values

GOL_RESULT_SUCCESS	Operation succeeded.
GOL_RESULT_UNKNOWN_SIMULATION_PROPERTY	Queried unknown property.

◆ gol_simulation_set_cells()

gol_result gol_simulation_set_cells	(	gol_simulation	simulation,
		gol_size	size,
		const gol_cell *	cells
	)

Update multiple simulation cells.

Since: 1.0.0

Modyfing same cell multiple times within a single call is allowed.
All updates are applied in order of cells array.
This operation mutates simulation state.
Simultaneus threads may call this function only with different simulation handles.

Parameters

[in]	simulation	Simulation to update.
[in]	size	Number of cells to update.
[in]	cells	Pointer for reading cells to update.

Return values

GOL_RESULT_SUCCESS Operation succeeded. All updates were applied.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ GOL_FALSE

◆ GOL_TRUE

Typedef Documentation

◆ gol_bool

◆ gol_grid_scalar

◆ gol_handle

◆ gol_simulation

◆ gol_simulation_property_frame_count

◆ gol_size

Enumeration Type Documentation

◆ gol_result

◆ gol_simulation_property_type

Function Documentation

◆ gol_simulation_create()

◆ gol_simulation_destroy()

◆ gol_simulation_get_alive_cells()

◆ gol_simulation_get_updated_cells()

◆ gol_simulation_next_frame()

◆ gol_simulation_query_cells()

◆ gol_simulation_query_property()

◆ gol_simulation_set_cells()