Flecs: Misc
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.1 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Misc
C API » Core » World
Collaboration diagram for Misc:

## Classes
struct | ecs_delete_empty_tables_desc_t
| Used with ecs_delete_empty_tables(). More...

## Macros
#define | flecs_poly_is(object, type)
| Test if a pointer is of the specified type.

## Typedefs
typedef struct ecs_delete_empty_tables_desc_t | ecs_delete_empty_tables_desc_t
| Used with ecs_delete_empty_tables().

## Functions
void | ecs_set_ctx (ecs_world_t *world, void *ctx, ecs_ctx_free_t ctx_free)
| Set a world context.
void | ecs_set_binding_ctx (ecs_world_t *world, void *ctx, ecs_ctx_free_t ctx_free)
| Set a world binding context.
void * | ecs_get_ctx (const ecs_world_t *world)
| Get the world context.
void * | ecs_get_binding_ctx (const ecs_world_t *world)
| Get the world binding context.
const ecs_build_info_t * | ecs_get_build_info (void)
| Get build info.
const ecs_world_info_t * | ecs_get_world_info (const ecs_world_t *world)
| Get the world info.
void | ecs_dim (ecs_world_t *world, int32_t entity_count)
| Dimension the world for a specified number of entities.
void | ecs_shrink (ecs_world_t *world)
| Free unused memory.
const ecs_entity_range_t * | ecs_entity_range_new (ecs_world_t *world, uint32_t min, uint32_t max)
| Create a new entity range.
void | ecs_entity_range_set (ecs_world_t *world, const ecs_entity_range_t *range)
| Set the active entity range.
const ecs_entity_range_t * | ecs_entity_range_get (const ecs_world_t *world)
| Get the currently active entity id range.
ecs_entity_t | ecs_get_max_id (const ecs_world_t *world)
| Get the largest issued entity ID (not counting generation).
void | ecs_run_aperiodic (ecs_world_t *world, ecs_flags32_t flags)
| Force aperiodic actions.
int32_t | ecs_delete_empty_tables (ecs_world_t *world, const ecs_delete_empty_tables_desc_t *desc)
| Clean up empty tables.
const ecs_world_t * | ecs_get_world (const ecs_poly_t *poly)
| Get the world from a poly.
ecs_entity_t | ecs_get_entity (const ecs_poly_t *poly)
| Get the entity from a poly.
bool | flecs_poly_is_ (const ecs_poly_t *object, int32_t type)
| Test if a pointer is of the specified type.
ecs_id_t | ecs_make_pair (ecs_entity_t first, ecs_entity_t second)
| Make a pair ID.
void | ecs_exclusive_access_begin (ecs_world_t *world, const char *thread_name)
| Begin exclusive thread access.
void | ecs_exclusive_access_end (ecs_world_t *world, bool lock_world)
| End exclusive thread access.

## Detailed Description

## Macro Definition Documentation

## ◆ flecs_poly_is

#define flecs_poly_is | ( |  | object,
|  |  | type )

Value:
flecs_poly_is_(object, type##_magic)
flecs_poly_is_
bool flecs_poly_is_(const ecs_poly_t *object, int32_t type)
Test if a pointer is of the specified type.

Test if a pointer is of the specified type.

See also
  flecs_poly_is_()

Definition at line 2872 of file flecs.h.

## Function Documentation

## ◆ ecs_delete_empty_tables()

int32_t ecs_delete_empty_tables | ( | ecs_world_t * | world,
|  | const ecs_delete_empty_tables_desc_t * | desc )

Clean up empty tables.

This operation cleans up empty tables that meet certain conditions. Having large amounts of empty tables does not negatively impact performance of the ECS, but can take up considerable amounts of memory, especially in applications with many components, and many components per entity.

The generation specifies the minimum number of times this operation has to be called before an empty table is cleaned up. If a table becomes non-empty, the generation is reset.

The operation allows for both a "clear" generation and a "delete" generation. When the clear generation is reached, the table's resources are freed (like component arrays) but the table itself is not deleted. When the delete generation is reached, the empty table is deleted.

By specifying a non-zero ID, the cleanup logic can be limited to tables with a specific (component) ID. The operation will only increase the generation count of matching tables.

The min_id_count specifies a lower bound for the number of components a table should have. Often the more components a table has, the more specific it is and therefore less likely to be reused.

The time budget specifies how long the operation should take at most.

The offset parameter specifies the table index at which to start scanning. The function loops around until it reaches this offset again, or until the time budget is exceeded.

Parameters

  world | The world.
  desc | Configuration parameters.

Returns
  The index + 1 of the table where the function stopped, or 0 if the function scanned all tables. The return value can be used as the offset for the next call.

## ◆ ecs_dim()

void ecs_dim | ( | ecs_world_t * | world,
|  | int32_t | entity_count )

Dimension the world for a specified number of entities.

This operation will preallocate memory in the world for the specified number of entities. Specifying a number lower than the current number of entities in the world will have no effect.

Parameters

  world | The world.
  entity_count | The number of entities to preallocate.

## ◆ ecs_entity_range_get()

const ecs_entity_range_t * ecs_entity_range_get | ( | const ecs_world_t * | world | ) |

Get the currently active entity id range.

Returns the range set by ecs_entity_range_set(), or NULL if no range is active.

Parameters

  world | The world.

Returns
  The active range, or NULL.

## ◆ ecs_entity_range_new()

const ecs_entity_range_t * ecs_entity_range_new | ( | ecs_world_t * | world,
|  | uint32_t | min,
|  | uint32_t | max )

Create a new entity range.

This function creates a range that constrains new entity identifiers returned by the specified [min, max] interval. Each range maintains its own list of recycled entity ids, which ensures that recycled ids always respect the configured range. If max is set to 0, the range is unbounded.

Entity ranges cannot be deleted once created. Use ecs_entity_range_set() to activate a range.

Parameters

  world | The world.
  min | The first entity id in the range (inclusive).
  max | The last entity id in the range (inclusive, 0 = unlimited).

Returns
  A pointer to the new range. Does not need to be freed.

## ◆ ecs_entity_range_set()

void ecs_entity_range_set | ( | ecs_world_t * | world,
|  | const ecs_entity_range_t * | range )

Set the active entity range.

This function activates a range created with ecs_entity_range_new(). When a range is activated, new entity identifiers will fall within the specified [min, max] interval, including recycled identifiers.

When the active range is out of available ids, operations that create new entity ids will assert.

The operation only accepts ranges that have been created by ecs_entity_range_new().

Parameters

  world | The world.
  range | The range to activate.

## ◆ ecs_exclusive_access_begin()

void ecs_exclusive_access_begin | ( | ecs_world_t * | world,
|  | const char * | thread_name )

Begin exclusive thread access.

This operation ensures that only the thread from which this operation is called can access the world. Attempts to access the world from other threads will panic.

ecs_exclusive_access_begin() must be called in pairs with ecs_exclusive_access_end(). Calling ecs_exclusive_access_begin() from another thread without first calling ecs_exclusive_access_end() will panic.

A thread name can be provided to the function to improve debug messages. The function does not copy the thread name, which means the memory for the name must remain alive for as long as the thread has exclusive access.

This operation should only be called once per thread. Calling it multiple times for the same thread will cause a panic.

Note that this feature only works in builds where asserts are enabled. The feature requires the OS API thread_self_ callback to be set.

Parameters

  world | The world.
  thread_name | The name of the thread obtaining exclusive access.

## ◆ ecs_exclusive_access_end()

void ecs_exclusive_access_end | ( | ecs_world_t * | world,
|  | bool | lock_world )

End exclusive thread access.

This operation should be called after ecs_exclusive_access_begin(). After calling this operation, other threads are no longer prevented from mutating the world.

When "lock_world" is set to true, no thread will be able to mutate the world until ecs_exclusive_access_begin() is called again. While the world is locked, only read-only operations are allowed. For example, ecs_get_id() is allowed, but ecs_get_mut_id() is not allowed.

A locked world can be unlocked by calling ecs_exclusive_access_end() again with lock_world set to false. Note that this only works for locked worlds. If ecs_exclusive_access_end() is called on a world that has exclusive thread access from a different thread, a panic will happen.

This operation must be called from the same thread that called ecs_exclusive_access_begin(). Calling it from a different thread will cause a panic.

Parameters

  world | The world.
  lock_world | When true, any mutations on the world will be blocked.

## ◆ ecs_get_binding_ctx()

void * ecs_get_binding_ctx | ( | const ecs_world_t * | world | ) |

Get the world binding context.

This operation retrieves a previously set world binding context.

Parameters

  world | The world.

Returns
  The context set with ecs_set_binding_ctx(). If no context was set, the function returns NULL.

## ◆ ecs_get_build_info()

const ecs_build_info_t * ecs_get_build_info | ( | void |  | ) |

Get build info.

Return information about the current Flecs build.

Returns
  A struct with information about the current Flecs build.

## ◆ ecs_get_ctx()

void * ecs_get_ctx | ( | const ecs_world_t * | world | ) |

Get the world context.

This operation retrieves a previously set world context.

Parameters

  world | The world.

Returns
  The context set with ecs_set_ctx(). If no context was set, the function returns NULL.

## ◆ ecs_get_entity()

ecs_entity_t ecs_get_entity | ( | const ecs_poly_t * | poly | ) |

Get the entity from a poly.

Parameters

  poly | A pointer to a poly object.

Returns
  The entity associated with the poly object.

## ◆ ecs_get_max_id()

ecs_entity_t ecs_get_max_id | ( | const ecs_world_t * | world | ) |

Get the largest issued entity ID (not counting generation).

Parameters

  world | The world.

Returns
  The largest issued entity ID.

## ◆ ecs_get_world()

const ecs_world_t * ecs_get_world | ( | const ecs_poly_t * | poly | ) |

Get the world from a poly.

Parameters

  poly | A pointer to a poly object.

Returns
  The world.

## ◆ ecs_get_world_info()

const ecs_world_info_t * ecs_get_world_info | ( | const ecs_world_t * | world | ) |

Get the world info.

Parameters

  world | The world.

Returns
  A pointer to the world info. Valid for as long as the world exists.

## ◆ ecs_make_pair()

ecs_id_t ecs_make_pair | ( | ecs_entity_t | first,
|  | ecs_entity_t | second )

Make a pair ID.

This function is equivalent to using the ecs_pair() macro, and is added for convenience to make it easier for non-C/C++ bindings to work with pairs.

Parameters

  first | The first element of the pair.
  second | The target of the pair.

Returns
  A pair ID.

## ◆ ecs_run_aperiodic()

void ecs_run_aperiodic | ( | ecs_world_t * | world,
|  | ecs_flags32_t | flags )

Force aperiodic actions.

The world may delay certain operations until they are necessary for the application to function correctly. This may cause observable side effects such as delayed triggering of events, which can be inconvenient when, for example, running a test suite.

The flags parameter specifies which aperiodic actions to run. Specify 0 to run all actions. Supported flags start with 'EcsAperiodic'. Flags identify internal mechanisms and may change unannounced.

Parameters

  world | The world.
  flags | The flags specifying which actions to run.

## ◆ ecs_set_binding_ctx()

void ecs_set_binding_ctx | ( | ecs_world_t * | world,
|  | void * | ctx,
|  | ecs_ctx_free_t | ctx_free )

Set a world binding context.

Same as ecs_set_ctx(), but for binding context. A binding context is intended specifically for language bindings to store binding-specific data.

Parameters

  world | The world.
  ctx | A pointer to a user-defined structure.
  ctx_free | A function that is invoked with ctx when the world is freed.

## ◆ ecs_set_ctx()

void ecs_set_ctx | ( | ecs_world_t * | world,
|  | void * | ctx,
|  | ecs_ctx_free_t | ctx_free )

Set a world context.

This operation allows an application to register custom data with a world that can be accessed anywhere where the application has the world.

Parameters

  world | The world.
  ctx | A pointer to a user-defined structure.
  ctx_free | A function that is invoked with ctx when the world is freed.

## ◆ ecs_shrink()

void ecs_shrink | ( | ecs_world_t * | world | ) |

Free unused memory.

This operation frees allocated memory that is no longer in use by the world. Examples of allocations that get cleaned up are:

- Unused pages in the entity index
- Component columns
- Empty tables

Flecs uses allocators internally for speeding up allocations. Allocators are not evaluated by this function, which means that the memory reported by the OS may not go down. For this reason, this function is most effective when combined with FLECS_USE_OS_ALLOC, which disables internal allocators.

Parameters

  world | The world.

## ◆ flecs_poly_is_()

bool flecs_poly_is_ | ( | const ecs_poly_t * | object,
|  | int32_t | type )

Test if a pointer is of the specified type.

Usage:

flecs_poly_is(ptr, ecs_world_t)
ecs_world_t
struct ecs_world_t ecs_world_t
A world is the container for all ECS data and supporting features.
Definition flecs.h:429
flecs_poly_is
#define flecs_poly_is(object, type)
Test if a pointer is of the specified type.
Definition flecs.h:2872

This operation only works for poly types.

Parameters

  object | The object to test.
  type | The ID of the type.

Returns
  True if the pointer is of the specified type.