TheZone/clay
1
0
Fork 0
mirror of https://github.com/nicbarker/clay.git synced 2025-04-20 21:28:03 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

readme updates

Browse Source
This commit is contained in:
Nic Barker 2024-12-26 19:06:39 +13:00
parent f49ec15da8
commit b62667dd10
2 changed files with 55 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@ -480,12 +480,30 @@ Takes a pointer to a function that can be used to measure the `width, height` di
**Note 2: It is essential that this function is as fast as possible.** For text heavy use-cases this function is called many times, and despite the fact that clay caches text measurements internally, it can easily become the dominant overall layout cost if the provided function is slow. **This is on the hot path!**
### Clay_SetMaxElementCount
`void Clay_SetMaxElementCount(uint32_t maxElementCount)`
Updates the internal maximum element count, allowing clay to allocate larger UI hierarchies.
**Note: You will need to reinitialize clay, after calling [Clay_MinMemorySize()](#clay_minmemorysize) to calculate updated memory requirements.**
### Clay_SetMaxMeasureTextCacheWordCount
`void Clay_SetMaxMeasureTextCacheWordCount(uint32_t maxMeasureTextCacheWordCount)`
Updates the internal text measurement cache size, allowing clay to allocate more text. The value represents how many seperate words can be stored in the text measurement cache.
**Note: You will need to reinitialize clay, after calling [Clay_MinMemorySize()](#clay_minmemorysize) to calculate updated memory requirements.**
### Clay_Initialize
`void Clay_Initialize(Clay_Arena arena, Clay_Dimensions layoutDimensions, Clay_ErrorHandler errorHandler)`
Initializes the internal memory mapping, sets the internal dimensions for layout, and binds an error handler for clay to use when something goes wrong.
Reference: [Clay_Arena](#clay_createarenawithcapacityandmemory), [Clay_ErrorHandler](#clay_errorhandler)
### Clay_SetLayoutDimensions
`void Clay_SetLayoutDimensions(Clay_Dimensions dimensions)`
@ -1542,6 +1560,29 @@ Element is subject to [culling](#visibility-culling). Otherwise, a single `Clay_
## Data Structures & Definitions
### Clay_String
```C
typedef struct {
int length;
const char *chars;
} Clay_String;
```
`Clay_String` is a string container that clay uses internally to represent all strings.
**Fields**
**`.length`** - `int`
The number of characters in the string, _not including an optional null terminator._
---
**`.chars`** - `const char *`
A pointer to the contents of the string. This data is not guaranteed to be null terminated, so if you are passing it to code that expects standard null terminated C strings, you will need to copy the data and append a null terminator.
### Clay_ElementId
```C
@ -1823,7 +1864,7 @@ An enum representing the type of error Clay encountered. It's up to the user to
- `CLAY_ERROR_TYPE_TEXT_MEASUREMENT_FUNCTION_NOT_PROVIDED` - The user is attempting to use `CLAY_TEXT` and either forgot to call [Clay_SetMeasureTextFunction](#clay_setmeasuretextfunction) or accidentally passed a null function pointer.
- `CLAY_ERROR_TYPE_ARENA_CAPACITY_EXCEEDED` - Clay was initialized with an Arena that was too small for the configured [Clay_SetMaxElementCount](#clay_setmaxelementcount). Try using [Clay_MinMemorySize()](#clay_minmemorysize) to get the exact number of bytes required by the current configuration.
- `CLAY_ERROR_TYPE_ELEMENTS_CAPACITY_EXCEEDED` - The declared UI hierarchy has too many elements for the configured max element count. Use [Clay_SetMaxElementCount](#clay_setmaxelementcount) to increase the max, then call [Clay_MinMemorySize()](#clay_minmemorysize) again and reinitialize clay's memory with the required size.
- `CLAY_ERROR_TYPE_ELEMENTS_CAPACITY_EXCEEDED` - The declared UI hierarchy has too much text for the configured text measure cache size. Use [Clay_SetMeasureTextCacheSize](#clay_setmeasuretextcachesize) to increase the max, then call [Clay_MinMemorySize()](#clay_minmemorysize) again and reinitialize clay's memory with the required size.
- `CLAY_ERROR_TYPE_ELEMENTS_CAPACITY_EXCEEDED` - The declared UI hierarchy has too much text for the configured text measure cache size. Use [Clay_SetMaxMeasureTextCacheWordCount](#clay_setmeasuretextcachesize) to increase the max, then call [Clay_MinMemorySize()](#clay_minmemorysize) again and reinitialize clay's memory with the required size.
- `CLAY_ERROR_TYPE_DUPLICATE_ID` - Two elements in Clays UI Hierarchy have been declared with exactly the same ID. Set a breakpoint in your error handler function for a stack trace back to exactly where this occured.
- `CLAY_ERROR_TYPE_FLOATING_CONTAINER_PARENT_NOT_FOUND` - A `CLAY_FLOATING` element was declared with the `.parentId` property, but no element with that ID was found. Set a breakpoint in your error handler function for a stack trace back to exactly where this occured.
- `CLAY_ERROR_TYPE_INTERNAL_ERROR` - Clay has encountered an internal logic or memory error. Please report this as a bug with a stack trace to help us fix these!

27
clay.h
View File

@ -144,9 +144,8 @@ typedef struct
} Clay__StringArray;
typedef struct {
Clay_String label;
uint64_t nextAllocation;
uint64_t capacity;
uintptr_t nextAllocation;
size_t capacity;
char *memory;
} Clay_Arena;
@ -479,7 +478,7 @@ Clay_RenderCommand * Clay_RenderCommandArray_Get(Clay_RenderCommandArray* array,
void Clay_SetDebugModeEnabled(bool enabled);
void Clay_SetCullingEnabled(bool enabled);
void Clay_SetMaxElementCount(uint32_t maxElementCount);
void Clay_SetMeasureTextCacheSize(uint32_t measureTextCacheSize);
void Clay_SetMaxMeasureTextCacheWordCount(uint32_t maxMeasureTextCacheWordCount);
// Internal API functions required by macros
void Clay__OpenElement();
@ -525,7 +524,7 @@ extern uint32_t Clay__debugViewWidth;
bool Clay__warningsEnabled = true;
uint32_t Clay__maxElementCount = 8192;
uint32_t Clay__measureTextCacheSize = 16384;
uint32_t Clay__maxMeasureTextCacheWordCount = 16384;
Clay_ErrorHandler Clay__errorHandler = CLAY__INIT(Clay_ErrorHandler) { .errorHandlerFunction = Clay__Noop };
void Clay__Noop() {};
@ -561,7 +560,7 @@ typedef struct
Clay__WarningArray Clay__WarningArray_Allocate_Arena(uint32_t capacity, Clay_Arena *arena) {
size_t totalSizeBytes = capacity * sizeof(Clay_String);
Clay__WarningArray array = CLAY__INIT(Clay__WarningArray){.capacity = capacity, .length = 0};
uintptr_t nextAllocAddress = (uintptr_t)arena->nextAllocation + (uintptr_t)arena->memory;
uintptr_t nextAllocAddress = arena->nextAllocation + (uintptr_t)arena->memory;
uintptr_t arenaOffsetAligned = nextAllocAddress + (CLAY__ALIGNMENT(Clay_String) - (nextAllocAddress % CLAY__ALIGNMENT(Clay_String)));
arenaOffsetAligned -= (uintptr_t)arena->memory;
if (arenaOffsetAligned + totalSizeBytes <= arena->capacity) {
@ -591,7 +590,7 @@ Clay__Warning *Clay__WarningArray_Add(Clay__WarningArray *array, Clay__Warning i
void* Clay__Array_Allocate_Arena(uint32_t capacity, uint32_t itemSize, uint32_t alignment, Clay_Arena *arena)
{
size_t totalSizeBytes = capacity * itemSize;
uintptr_t nextAllocAddress = (uintptr_t)arena->nextAllocation + (uintptr_t)arena->memory;
uintptr_t nextAllocAddress = arena->nextAllocation + (uintptr_t)arena->memory;
uintptr_t arenaOffsetAligned = nextAllocAddress + (alignment - (nextAllocAddress % alignment));
arenaOffsetAligned -= (uintptr_t)arena->memory;
if (arenaOffsetAligned + totalSizeBytes <= arena->capacity) {
@ -1577,7 +1576,7 @@ Clay__MeasureTextCacheItem *Clay__MeasureTextCached(Clay_String *text, Clay_Text
return NULL;
}
uint32_t id = Clay__HashTextWithConfig(text, config);
uint32_t hashBucket = id % (Clay__measureTextCacheSize / 8);
uint32_t hashBucket = id % (Clay__maxMeasureTextCacheWordCount / 8);
int32_t elementIndexPrevious = 0;
int32_t elementIndex = Clay__measureTextHashMap.internalArray[hashBucket];
while (elementIndex != 0) {
@ -1647,7 +1646,7 @@ Clay__MeasureTextCacheItem *Clay__MeasureTextCached(Clay_String *text, Clay_Text
if (!Clay__booleanWarnings.maxTextMeasureCacheExceeded) {
Clay__errorHandler.errorHandlerFunction(CLAY__INIT(Clay_ErrorData) {
.errorType = CLAY_ERROR_TYPE_TEXT_MEASUREMENT_CAPACITY_EXCEEDED,
.errorText = CLAY_STRING("Clay has run out of space in it's internal text measurement cache. Try using Clay_SetMeasureTextCacheSize() (default 16384, with 1 unit storing 1 measured word)."),
.errorText = CLAY_STRING("Clay has run out of space in it's internal text measurement cache. Try using Clay_SetMaxMeasureTextCacheWordCount() (default 16384, with 1 unit storing 1 measured word)."),
.userData = Clay__errorHandler.userData });
Clay__booleanWarnings.maxTextMeasureCacheExceeded = true;
}
@ -2028,9 +2027,9 @@ void Clay__InitializePersistentMemory(Clay_Arena *arena) {
Clay__layoutElementsHashMap = Clay__int32_tArray_Allocate_Arena(Clay__maxElementCount, arena);
Clay__measureTextHashMapInternal = Clay__MeasureTextCacheItemArray_Allocate_Arena(Clay__maxElementCount, arena);
Clay__measureTextHashMapInternalFreeList = Clay__int32_tArray_Allocate_Arena(Clay__maxElementCount, arena);
Clay__measuredWordsFreeList = Clay__int32_tArray_Allocate_Arena(Clay__measureTextCacheSize, arena);
Clay__measuredWordsFreeList = Clay__int32_tArray_Allocate_Arena(Clay__maxMeasureTextCacheWordCount, arena);
Clay__measureTextHashMap = Clay__int32_tArray_Allocate_Arena(Clay__maxElementCount, arena);
Clay__measuredWords = Clay__MeasuredWordArray_Allocate_Arena(Clay__measureTextCacheSize, arena);
Clay__measuredWords = Clay__MeasuredWordArray_Allocate_Arena(Clay__maxMeasureTextCacheWordCount, arena);
Clay__pointerOverIds = Clay__ElementIdArray_Allocate_Arena(Clay__maxElementCount, arena);
Clay__debugElementData = Clay__DebugElementDataArray_Allocate_Arena(Clay__maxElementCount, arena);
Clay__arenaResetOffset = arena->nextAllocation;
@ -3830,9 +3829,9 @@ void Clay_SetMaxElementCount(uint32_t maxElementCount) {
Clay__maxElementCount = maxElementCount;
}
CLAY_WASM_EXPORT("Clay_SetMeasureTextCacheSize")
void Clay_SetMeasureTextCacheSize(uint32_t measureTextCacheSize) {
Clay__measureTextCacheSize = measureTextCacheSize;
CLAY_WASM_EXPORT("Clay_SetMaxMeasureTextCacheWordCount")
void Clay_SetMaxMeasureTextCacheWordCount(uint32_t maxMeasureTextCacheWordCount) {
Clay__maxMeasureTextCacheWordCount = maxMeasureTextCacheWordCount;
}
#endif //CLAY_IMPLEMENTATION