What are we doing?

Converting cute_framework headers to be C compatible, while leaving an optional namespaced C++ API in place.

What work is remaining?

• [x] Prefix all types, functions, and globals with cf_
• [X] Remove the cute namespace from everything part of the C api
• [x] Wrap the namespaced c++ api inside #ifdef CUTE_CPP
• [x] Alias cf_ prefixed types inside namespaces with their original short name
• [x] Move member function implementations into free functions
• [x] Replace default arguments in functions
• [x] Rename overloaded functions with a numerical or type postfix
• [x] Replace usage of templated types in C api
• [x] Replace using statements with typedefs
• [x] Typedef all structs
• [x] Surround C api with extern "C"
• [x] Add #ifdef CUTE_NO_CPP to cute_defines.h for C-only mode when compiling as C++
• [x] Merge latest from cute_framework/main
• [x] Verify that all cute headers compile in a C99 project
• [ ] Verify that all changes compile using emscripten

Per-file progress

• [x] cute_a_star.h
• [x] cute_aabb_tree.h
• [x] cute_alloc.h
• [x] cute_app.h
• [x] cute_array.h
• [x] cute_aseprite_cache.h
• [x] cute_audio.h
• [x] cute_base64.h
• [x] cute_batch.h
• [x] cute_c_runtime.h
• [x] cute_circular_buffer.h
• [x] cute_clipboard.h
• [x] cute_color.h
• [x] cute_concurrency.h
• [x] cute_coroutine.h
• [x] cute_debug_printf.h
• [x] cute_defer.h
• [x] cute_defines.h
• [x] cute_dictionary.h
• [x] cute_doubly_list.h
• [x] cute_ecs.h
• [x] cute_error.h
• [x] cute_file_system.h
• [x] cute_file_system_utils.h
• [x] cute_font.h
• [x] cute_gfx.h
• [x] cute_handle_table.h
• [x] cute_haptics.h
• [x] cute_hashtable.h
• [x] cute_https.h
• [x] cute_image.h
• [x] cute_input.h
• [x] cute_joypad.h
• [x] cute_kv.h
• [x] cute_kv_utils.h
• [x] cute_lru_cache.h
• [x] cute_math.h
• [x] cute_memory_pool.h
• [x] cute_networking.h
• [x] cute_png_cache.h
• [x] cute_priority_queue.h
• [x] cute_rnd.h
• [x] cute_sprite.h
• [x] cute_string.h
• [x] cute_string_utils.h
• [x] cute_strpool.h
• [x] cute_symbol.h
• [x] cute_timer.h
• [x] cute_typeless_array.h
• [x] cute_utf8.h
• [x] cute_version.h
• [x] cute_window.h

Notes from discord chat

[10:20 PM] Randy: The main problem would be the usage of templated data structures in the implementation of some of the features, like the serialization and the ECS
[10:21 PM] Randy: However, it's possible to compile a C interface and leave the implementation using some C++
[10:21 PM] Randy: Then the main pain point is just some of the templated stuff in the API, but it's not too much
[10:21 PM] Limyc: I'm mostly interested in a c interface, and if it's just some grunt work, I might just do it
[10:22 PM] Randy: It's not a big deal to write C versions of function overloads and whatnot
[10:22 PM] Randy: I would absolutely support you here. I would do it myself, but priorities dictate I work on the other things first, like docs and bugs
[10:22 PM] Randy: So if you do it, that would super awesome
[10:25 PM] Limyc: is there a particular way you would want the interface work done?
[10:26 PM] Randy: https://github.com/RandyGaul/cute_headers/blob/master/cute_sound.h
GitHub
[cute_headers/cute_sound.h at master · RandyGaul/cute_headers](https://github.com/RandyGaul/cute_headers/blob/master/cute_sound.h)
Collection of cross-platform one-file C/C++ libraries with no dependencies, primarily used for games - cute_headers/cute_sound.h at master · RandyGaul/cute_headers
cute_headers/cute_sound.h at master · RandyGaul/cute_headers
[10:27 PM] Randy: This is a pretty good way to create C versions without default arguments
[10:27 PM] Randy:
cs_audio_source_t* cs_load_wav(const char* path, cs_error_t* err /* = NULL */);
cs_audio_source_t* cs_read_mem_wav(const void* memory, size_t size, cs_error_t* err /* = NULL */);
[10:27 PM] Randy: In each header you can #ifdef __cplusplus the C++ header, and in the #else have the C versions
[10:28 PM] Randy: For overloaded functions you can append 2 to the name
[10:28 PM] Randy: Should probably also have a macro to force C-only as an optional macro
[10:29 PM] Limyc: Would you want to keep the namespaced C++ functions wrapped with #ifdef _cplusplus, and those just call into the cf_* functions?
[10:29 PM] Randy: Yeah I think that's a good way to do it
[10:29 PM] Randy: In the places where an array<T> is returned there's a few options on what to do
[10:30 PM] Randy: We can probably discuss those case-by-case
[10:33 PM] Randy: cute_string.h should probably not have a C version at all
[10:33 PM] Randy: I see array<T> in cute_ecs.h and cute_https.h
[10:33 PM] Randy: but those should be easy to change to a C-style implementation
[10:35 PM] Randy: Overall it's a straightforward port to C
[10:35 PM] Limyc: okay, so globals, functions, types all get cf_
overloads get a numerical postfix.
keep the namespaced functions wrapped by an ifdef
deal with templates on a case-by-case basis
[10:35 PM] Randy: sounds pretty good
[10:35 PM] Randy: And ask questions if you need help with anything, we can always discuss things if you're unsure which option to take
[10:37 PM] Limyc: do you want to alias types inside the cpp namespace for convenience and not breaking anyone who updates?
namespace cute {
using ecs_entity_t = cf_ecs_entity_t;
}
 
[10:37 PM] Randy: yeah that's a good idea
[10:38 PM] Randy: that works well
[10:38 PM] Randy: Probably the big one here would be the sprite
[10:39 PM] Randy: https://github.com/RandyGaul/cute_framework/blob/master/include/cute_handle_table.h
[10:39 PM] Randy: Here's a similar example to how the sprite can be implemented. The C version is the "main" version and the C++ one just calls into the C functions and holds the struct instance
[10:40 PM] Randy: But the sprite would still just be POD style as opposed to the handle_table is heap allocated

Hi Randy, my pointer math might be a little rusty, but shouldn't this line detect if memory is in [lo, hi] memory bounds?

https://github.com/RandyGaul/cute_framework/blob/master/src/cute_memory_pool.cpp#L97

My code for memory pool is similar to yours, but for inside memory bounds test in my code I use:

int stride = element_size > sizeof(void*) ? element_size : sizeof(void*); int in_bounds = (uint8_t*)element >= arena && (uint8_t*)element + stride <= arena + arena_size;

Hi RandyGaul I created online documentation for cute_framework, using docsify.js, and customized the theme, and it looks pretty good, The cute_framework doc online address is here, if you think it's ok, I'll be happy to pull request

Currently we have two sprite-related APIs -- png and aseprite support. The PNG option is a bit lower level, but the easy_*** API also uses PNGs. This is good, but the issue is that new users to CF will get confused about which batch to use. There should probably just be a single batch used as a global completely hidden from the sprite API. It should not be possible to accidentally use the PNG batch with the aseprite batch.

8:43 PM] Limyc: How can I check if I'm going to overflow the sg_buffer with the current batch? I'm rendering circles using batch_circle_line and I assert when I hit around 171 circles using an iter count of 10. It asserts at lower circle counts if I draw  higher resolution circles.
sg_append_buffer: overall appended size is bigger than buffer size
[8:44 PM] Randy: https://github.com/RandyGaul/cute_framework/blob/master/src/cute_batch.cpp#L391
[8:44 PM] Randy: it's hard coded for now
[8:45 PM] Randy: Feel free to add a simple function to adjust or get the buffer size
[8:50 PM] Limyc: okay, so for now, there's no way to check if adding something to the batch will exceed the buffer size. I'll need to write that myself
[8:51 PM] Limyc: Would it make sense for CF to split batches up automatically if they are too big?
[8:51 PM] Randy: https://github.com/RandyGaul/cute_framework/blob/master/src/cute_gfx.cpp#L120-L141
[8:51 PM] Randy: Well sokol_gfx is supposed to be dropping draw calls silently if you overflow
[8:52 PM] Randy: But maybe sokol_gfx was changed
[8:52 PM] Randy: And added that nice error message you found
[8:54 PM] Limyc: looks like you can define SOKOL_VALIDATE_NON_FATAL to silently drop overflowed calls
[8:54 PM] Randy: ah that sounds new to me
[8:54 PM] Randy: the perks of using actively maintained software 🙂
[8:56 PM] Limyc: Validation starts here: https://github.com/RandyGaul/cute_framework/blob/master/libraries/sokol/sokol_gfx.h#L15465
And asserts here: https://github.com/RandyGaul/cute_framework/blob/master/libraries/sokol/sokol_gfx.h#L13690
[8:56 PM] Limyc: Should I make an issue for this? If so, what exactly?
[8:57 PM] Randy: Make a pull request
[8:57 PM] Randy: Unless you want me to try and change things
[8:58 PM] Randy: Then go ahead and make an issue, you can just screenshot our convo here, or post in the relevant details
[9:00 PM] Limyc: okay, I'll make an issue then. I think it's worth considering friendlier ways to detecting and handling overflows instead of dropping the draw calls silently.
[9:01 PM] Limyc: I'm not sure how I'd use triple_buffer_append as the public CF api currently stands, and maybe that's the solution and there's just missing docs or an example 
[9:02 PM] Randy: the triple_buffer_apped is lower level
[9:02 PM] Randy: you shouldn't have to deal with it directly when using the batch api
[9:02 PM] Randy: I think not silently dropping the calls is a good thing
[9:03 PM] Randy: Just need to expose a getter/setter for the buffer size
[9:04 PM] Limyc: yeah, I'd rather have the assert than not. What's missing is an easy way to detect the overflow at draw time and handle it 

Reference: https://github.com/mattiasgustavsson/libs/blob/main/cstr.h

Currently there are some issues such as destructing in unintended ways. Also the issue of single-threadedness clashes with common intuition about how std::string works.

Various topics to mull over:

• utf8 + utf16
• stack vs heap storage
• interning
• path helper funcs
• common utils (like trim, find first of, split, etc.)
• multithreading (rw lock?)

Try to building cute_framework on my macOS 12.4,the 3.0 version mbedtls will make "parameter 'output_size' set but not used" error,upgrade to the newer 3.1 will fix it(set GIT_TAG to v3.1.0).

Currently CF drops draw calls if too much data is requested to be sent to the GPU and issues a printed warning to stderr. This should work fairly well for development, but, an alternative may be much better.

Instead of dropping the draw call the vertices can be stored on the CPU in temporary memory, to be flushed to the GPU later. This would allow the entire system to handle temporary stalls in framerate, and simply render things a bit slower until the GPU catches up. The temporary overflow buffer can also fill up, at which point the entire CPU needs to hang and wait for the GPU, and a loud warning can be printed that to explain how the entire process is simply GPU bound.

add this

struct entity_config_t
{
	const char* entity_name;
	array<const char*> component_types;
};

void app_register_entity_type(app_t* app, entity_config_t entity_config);

Thought of a way to optimize the sprite outline effect by trading a little more GPU memory. Another texture can be formed to compress alpha transparency down to 1 bit per pixel. Each bit can be packed into 8 bits per pixel for a monochrome texture. Addressing can easily compute which bit from which pixel represents empty color or opaque color. Using this simple compression format each texture atlas can have an associated outline texture. All outline pixels can be baked into this texture. The size would be 32x smaller than a full RGBA (4 bytes per pixel) image.

This is a great tradeoff. The amount of extra memory required is very small. We then reduce the outline shader's 9 texture taps for outlines to 1 texture tap. Complexity wise the implementation would also be very simple -- each atlas would have an associated outline map bound to the batch shader.

https://github.com/RandyGaul/cute_framework/blob/d48eebc8c1bf3764763b276f2283a37de4ec4789/include/cute_defines.h#L123

#if defined(CUTE_WINDOWS)
#	define SOKOL_D3D11
#elif defined(CUTE_LINUX)
#	define SOKOL_GLCORE33
#elif defined(CUTE_MACOSX)
#	define SOKOL_GLCORE33
#elif defined(CUTE_EMSCRIPTEN)
#	define SOKOL_GLES3
#	include <emscripten.h>
#endif

This line allocates only a single element:

https://github.com/RandyGaul/cute_framework/blob/master/src/cute_typeless_array.cpp#L39

I think it should be modified to

m_items = CUTE_ALLOC(m_element_size * m_capacity);

Please feel free to correct me if I'm wrong.

Kariem had a cool idea on Discord. CF could have a push/pop API for adding custom rendering to cute_draw.h. Here are the notes from our Discord discussion so these don't get lost. I don't have this slated for V1.00, but Kariem mentioned they may be interested in pursuing a PR at some point.

• Custom uniforms - Simply forward these straight to the material. The material can hold a large number of uniforms and will only send matches to the shader.
• Custom shaders - By passing a CF_SokolShader we can easily swap to a new custom shader.
• Custom vertex attributes - This is the trickier one. The vertices and their attribute layout can be mostly seen in cute_draw_internal.h, and the draw context itself is called CF_Draw. A simple idea that could be good to start with is to add in e.g. 4 unused components per vertex. This can be allocated for custom usage. They'll get mapped dynamically to shader inputs by matching names. We can accept an array of CF_VertexAttribute's. CF_Draw uses 4 attributes by default, leaving 4 open for custom purposes. A full array of 8 attributes can be formed by concatenating the 4 used by CF_Draw and the 4 user supplied attributes. Then they can be set onto CF_Draw::mesh by cf_mesh_set_attributes.
• Custom draw order - cf_render_to can draw at any time, in any sokol_gfx pass to any CF_Canvas, where CF_Canvas maps to a sokol_gfx pass.
• Custom vertices can be filled in by the user with a callback? I'm not exactly sure what the best way here is. The purpose would be to let the user fill in those 4 custom attributes each time a vertex is emit.
• All of these would probably fall under cf_draw_settings_*** style functions.
• Finally, we can push/pop the entire draw context itself. This can let the user store a reference to their own custom draw contexts. By default, CF will keep it's default context on the bottom of the stack.

CF headers have a C and C++ section. To save on dev-time, for now, only the C functions are documented with in-code comments. The C++ functions are almost all tiny inline stubs that simply call into the C functions, so this seems like a good strategy.

Generating online documentation (https://randygaul.github.io/cute_framework/#/app/) is critical to hit v1.00. However, writing these doc pages for each function by hnad has been an incredible task. The online documentation desyncs with on-code docs over time, and it takes way too much time to write them in the first place. It may be best to implement a code parser to generate the bulk of individual function pages. I wouldn't want to use doxygen as I'd like to output custom formatted .md files in a very specific way.

There will be a couple types of online documentation pages:

• One page per function, talking about what the function does, it's parameters, related functions, etc. This is a great target to generate with a comment parser.
• Tutorials on specific topics. These will be hand-written.
• Documentation about API groups/areas. These will be hand-written.

The idea actually comes from raylib (https://github.com/raysan5/raylib). But instead of generating reflection data, this is specifically just to generate online documentation.

Shouldn't the stack count/pointer sp in this line be less than or equal to capacity?

https://github.com/RandyGaul/cute_framework/blob/master/src/cute_aabb_tree.cpp#L784

E.g.:

CUTE_ASSERT(sp <= AABB_TREE_STACK_QUERY_CAPACITY);