- **14-Jan-2023**: sokol_app.h x11: a drag'n'drop related bugfix, the
XdndFinished reply event was sent with the wrong window handle which
confused some apps where the drag operation originated
(see https://github.com/floooh/sokol/pull/765#issuecomment-1382750611)
- **16-Dec-2022**: In the sokol_gfx.h Metal backend: A fix for a Metal
validation layer error which I just discovered yesterday (seems to be new in
macOS 13). When the validation layer is active, and the application window
becomes fully obscured, the validation layer throws an error after a short
time (for details see: https://github.com/floooh/sokol/issues/762).
The reason appears to be that sokol_gfx.h creates a command buffer with
'unretained references' (e.g. the command buffer doesn't manage the
lifetime of resources used by the commands stored in the buffer). This
seems to clash with MTKView's and/or CAMetalLayer's expectations. I fixed
this now by creating a second command buffer with 'retained references',
which only holds the ```presentDrawable``` command. That way, regular
draw commands don't have the refcounting overhead (because they're stored
in an unretained-references cmdbuffer), while the drawable surface is
still properly lifetime managed (because it's used in a separate command
buffer with retained references).
- **15-Dec-2022**: A small but important update in sokol_imgui.h which fixes
touch input handling on mobile devices. Many thanks to github user @Xadiant
for the bug investigation and [PR](https://github.com/floooh/sokol/pull/760).
- **25-Nov-2022**: Some code cleanup around resource creation and destruction in sokol_gfx.h:
- It's now safe to call the destroy, uninit and dealloc functions in any
resource state, in general, the functions will do the right thing without
assertions getting in the way (there are however new log warnings in some
cases though, such as attempting to call an ```sg_dealloc_*()``` function on
a resource object that's not in ALLOC state)
- A related **minor breaking change**: the ```sg_uninit_*()``` functions now return
void instead of bool, this is because ```sg_dealloc_*()``` no longer asserts
when called in the wrong resource state
- Related internal code cleanup in the backend-agnostic resource creation
and cleanup code, better or more consistent function names, etc...
- The validation layer can now be disabled in debug mode with a runtime
flag during setup: ```sg_desc.disable_validation```. This is mainly useful
for test code.
- Creating a pass object with invalid image objects now no longer asserts,
but instead results in a pass object in FAILED state. In debug mode,
the validation layer will still stop at this problem though (it's mostly
an 'undefined API behaviour' fix in release mode).
- Calling ```sg_shutdown()``` with existing resources in ALLOC state will
no longer print a log message about an 'active context mismatch'.
- A new header documentation blurb about the two-step resource creation
and destruction functions (search for RESOURCE CREATION AND DESTRUCTION IN DETAIL)
- **16-Nov-2022**: Render layer support has been added to sokol_debugtext.h,
same general changes as in sokol_gl.h with two new functions:
sdtx_layer(layer_id) to select the layer to record text into, and
sdtx_draw_layer(layer_id) to draw the recorded text in that layer inside a
sokol-gfx render pass. The new sample [debugtext-layers-sapp](https://floooh.github.io/sokol-html5/debugtext-layers-sapp) demonstrates the feature together with
sokol-gl.
- **11-Nov-2022**: sokol_gl.h has 2 new public API functions which enable
layered rendering: sgl_layer(), sgl_draw_layer() (technically it's three
functions: there's also sgl_context_draw_layer(), but that's just a variant of
sgl_draw_layer()). This allows to 'interleave' sokol-gl rendering
with other render operations. The [spine-layers-sapp](https://floooh.github.io/sokol-html5/spine-layers-sapp.html)
sample has been updated to use multiple sokol-gl layers.
- **09-Nov-2022**: sokol_gfx.h now allows to add 'commit listeners', these
are callback functions which are called from inside sg_commit(). This is
mainly useful for libraries which build on top of sokol-gfx to be notified
about the start/end point of a frame, which in turn may simplify the public
API, or the internal implementation, because the library no longer needs to
'guess' when a new frame starts.
For more details, search for 'COMMIT LISTENERS' in the sokol_gfx.h header.
This also results in a minor breaking change in sokol_spine.h: The function
```sspine_new_frame()``` has been removed and replaced with an internal commit
listener.
Likewise, sokol_gl.h now uses a commit listener in the implementation, but
without changing the public API (the feature will be important for an upcoming
sokol-gl feature to support rendering layers, and for this a 'new-frame-function'
would have been needed).
- **05-Nov-2022** A breaking change in sokol_fetch.h, and a minor change in
sokol_app.h which should only break for very few users:
- An ```sfetch_range_t``` ptr/size pair struct has been added to sokol_fetch.h,
and discrete ptr/size pairs have been replaced with sfetch_range_t
items. This affects the structs ```sfetch_request_t``` and ```sfetch_response_t```,
and the function ```sfetch_bind_buffer()```.
- The required changes in ```sfetch_response_t``` might be a bit non-obviois: To
access the fetched data, previous ```.buffer_ptr``` and ```.fetched_size```
was used. The fetched data is now accessible through an ```sfetch_range_t data```
item (```data.ptr``` and ```data.size```). The old ```.fetched_offset``` item
has been renamed to ```.data_offset``` to better conform with the new naming.
- The last two occurrences of discrete ptr/size pairs in sokol_app.h now have also
been replaced with ```sapp_range_t``` items, this only affects the structs
```sapp_html5_fetch_request``` and ```sapp_html5_fetch_response```.
- **03-Nov-2022** The language bindings generation has been updated for Zig 0.10.0,
and clang-14 (there was a minor change in the JSON ast-dump format).
Many thanks to github user @kcbanner for the Zig PR!
- **02-Nov-2022** A new header sokol_spine.h (in the util dir), this is a
renderer and 'handle wrapper' around the spine-c runtime (Spine is a popular 2D
character anim system: http://esotericsoftware.com/). This turned out a much bigger
rabbit-hole than I initially expected, but the effort is justified by being a
experimentation testbed for a couple of things I want to add to other sokol
headers (for instance cleaned up handle pool code, a new logging- and error-reporting
system, render layers which will be useful for sokol_gl.h and sokol_debugtext.h).
- **22-Oct-2022** All sokol headers now allow to override logging with a
callback function (installed in the setup call) instead of defining a SOKOL_LOG
macro. Overriding SOKOL_LOG still works as default fallback, but this is no
longer documented, consider this deprecated. Many thanks to github user
@Manuzor for the PR (see https://github.com/floooh/sokol/pull/721 for details)
- **21-Oct-2022** RGB9E5 pixel format support in sokol_gfx.h and a GLES2 related
bugfix in the sokol_app.h Android backend:
- sokol_gfx.h now supports RGB9E5 textures (3*9 bit RGB + 5 bit shared exponent),
this works in all backends except GLES2 and WebGL1 (use ```sg_query_pixelformat()```
to check for runtime support). Many thanks to github user @allcreater for the PR!
- a bugfix in the sokol_app.h Android backend: when forcing a GLES2 context via
sapp_desc.gl_force_gles2, the Android backend correctly created a GLES2 context,
but then didn't communicate this through the function ```sapp_gles2()``` (which
still returned false in this case). This caused the sokol_gfx.h GL backend to
use the GLES3 code path instead GLES2 (which surprisingly seemed to have worked
fine, at least for the sokol samples which force GLES2).
- **19-Oct-2022** Some fixes in the embedded Javascript code blocks (via EM_JS)
in sokol_app.h, sokol_args.h, sokol_audio.h and sokol_fetch.h:
- the JS code has been 'modernized' (e.g. const and let instead of var,
```() => { ... }``` instead of ```function () { ... }``` for callbacks)
- false positives in the Closure static analysis have been suppressed
via inline hints
- **16-Oct-2022** The Odin bindings generator and the generated bindings have
been simplified (the Odin binding now don't have separate wrapper functions).
Requires the latest Odin release. Also note: On M1 Macs I'm currently seeing
what looks like an ABI problem (in functions which pass color values to the C
side as uint8_t, the colors come out wrong). This also happened with the
previous binding version, so it looks like a regression in Odin. Might be
related to this recent bugfix (which I haven't tested yet):
https://github.com/odin-lang/Odin/issues/2121 Many thanks to @thePHTest for the
PR! (https://github.com/floooh/sokol/pull/719)
- **15-Oct-2022**
- fixes for Emscripten 3.1.24: the sokol headers now use the new
**EM_JS_DEPS()** macro to declare 'indirect dependencies on JS library functions'.
This is a (much more robust) follow-up fix to the Emscripten related fixes from 10-Sep-2022.
The new Emscripten SDK also displays a couple of Javascript "static analyzer" warnings
by the Closure compiler (used in release mode to optimize and minify the generated
JS code). I fixed a couple of those warnings, but some warnings persist (all of them
false positives). Not sure yet if these can be fixed or need to be suppressed, but
that's for another time.
- the webkitAudioContext() fallback in sokol_audio.h's Emscripten backend
has been removed (only AudioContext is supported now), the fallback also
triggered a Closure warning, so it probably never worked as intended anyway.
- I also had to undo an older workaround in sokol_app.h on iOS (https://github.com/floooh/sokol/issues/645)
because this is now triggering a Metal validation layer error (https://github.com/floooh/sokol/issues/726).
The original case is no longer reproducible, so undoing the old workaround seems to
be a quick fix. Eventually I want to get rid of MTKView though, and go down to
CAMetalLayer.
- **08-Oct-2022** sokol_app.h Android backend: the ```sapp_touchpoint``` struct
now has a new item ```sapp_android_tooltype android_tooltype;```. This exposes the
result of the Android NDK function ```AMotionEvent_getToolType()```.
Many thanks to @Wertzui123 for the initial PR (https://github.com/floooh/sokol/pull/717).
- **25-Sep-2022**: sokol_app.h on Linux now optionally supports EGL instead of
GLX for the window system glue code and can create a GLES2 or GLES3 context
instead of a 'desktop GL' context.
To get EGL+GLES2/GLES3, just define SOKOL_GLES2 or SOKOL_GLES3 to compile the
implementation. To get EGL+GL, define SOKOL_GLCORE33 *and* SOKOL_FORCE_EGL.
By default, defining just SOKOL_GLCORE33 uses GLX for the window system glue
(just as before). Many thanks to GH user @billzez for the PR!
- **10-Sep-2022**: sokol_app.h and sokol_args.h has been fixed for Emscripten 3.21, those headers
used the Emscripten Javascript helper function ```ccall()``` which is now part of the
'legacy runtime' and causes linker errors. Instead of ```ccall()``` sokol_app.h and sokol_args.h
now drop down to a lower level set of Emscripten JS helper functions (which hopefully won't
go away anytime soon).
- **05-Aug-2022**: New officially supported and automatically updated language bindings for Odin:
https://github.com/floooh/sokol-odin (also see [gen_odin.py](https://github.com/floooh/sokol/blob/master/bindgen/gen_odin.py))
- **10-Jul-2022**: New features in sokol_app.h and sokol_imgui.h:
- In sokol_app.h it's now possible to set a mouse cursor type from a number of predefined
types via the new function ```sapp_set_mouse_cursor(sapp_mouse_cursor cursor)```. The
available cursor types are compatible with GLFW and Dear ImGui. Supported platforms
are: macOS, linux, win32, uwp and web.
- ```sapp_show_mouse(bool shown)``` now also works on the web platform.
- In sokol_app.h, the poorly defined 'user cursor' feature has been removed (```sapp_desc.user_cursor```
and ```SAPP_EVENTTYPE_UPDATE_CURSOR```). This was a hack to allow changing the mouse cursor and
only worked on Win32 and macOS (with different behaviour). Since setting the cursor type
is now 'properly supported, this hack was removed.
- sokol_imgui.h will now set the cursor type via ```sapp_set_mouse_cursor()```. This can be
disabled with the new ```simgui_desc_t``` item ```disable_set_mouse_cursor```.
- sokol_imgui.h now automatically enables resizing windows from edges (not just the bottom-right corner),
this behaviour can be disabled with the new ```simgui_desc_t``` item ```disable_windows_resize_from_edges```.
- sokol_imgui.h can now optionally write to the alpha channel (useful if you want to render the UI
into a separate render target, which is later composed onto the default framebuffer). The feature
is enabled with the new ```simgui_desc_t``` item ```write_alpha_channel```.
Many thanks to **@tomc1998** for the initial [Linux/X11 mouse cursor type PR](https://github.com/floooh/sokol/pull/678) and
**@luigi-rosso** for the [sokol_imgui.h alpha channel PR](https://github.com/floooh/sokol/pull/687)!
- **03-Jul-2022**: A new sokol_gfx.h function ```bool sg_query_buffer_will_overflow(sg_buffer buf, size_t size)```
which allows to check if a call to ```sg_append_buffer()``` would overflow the buffer. This
is an alternative to the ```sg_query_buffer_overflow()``` function which only reports
the overflow after the fact. Many thanks to @RandyGaul for the PR!
- **29-Jun-2022**: In sokol_app.h with the D3D11 backend, if SOKOL_DEBUG is
defined, and the D3D11 device creation fails, there's now a fallback code
path which tries to create the device again without the D3D11_CREATE_DEVICE_DEBUG
flag. Turns out the D3D11 debug support may suddenly stop working (just happened
to me, indicated by the Win10 "Graphics Tool" feature being silently uninstalled
and failing to install when asked to do so). This fix at least allows sokol_app.h
applications compiled in debug mode to run, even if the D3D11 debug layer doesn't
work.
- **29-May-2022**: The code generation scripts for the
[sokol-nim](https://github.com/floooh/sokol-nim) language bindings have been
revised and updated, many thanks to Gustav Olsson for the PR! (I'm planning to
spend a few more days integrating the bindings generation with Github Actions,
so that it's easier to publish new bindings after updates to the sokol headers).
- **26-May-2022**: The GL backend in sokol_app.h now allows to override the GL
context version via two new items in the ```sapp_desc``` struct:
```sapp_desc.gl_major_version``` and ```sapp_desc.gl_minor_version```. The
default GL context version remains at 3.2. Overriding the GL version might make
sense if you're not using sokol_app.h together with sokol_gfx.h, or otherwise
want to call GL functions directly. Note that this only works for the
'desktop GL' backends (Windows, Linux and macOS), but not for the GLES backends
(Android, iOS, web). Furthermore, on macOS only the GL versions 3.2 and 4.1
are available (plus the special config major=1 minor=0 creates an
NSOpenGLProfileVersionLegacy context). In general: use at your risk :) Many
thanks to Github user @pplux for the PR!
- **15-May-2022**: The way internal memory allocation can be overridden with
your own functions has been changed from global macros to callbacks
provided in the API setup call. For instance in sokol_gfx.h:
```c
void* my_malloc(size_t size, void* userdata) {
(void)userdata; // unused
return malloc(size);
}
void my_free(void* ptr, void* userdata) {
(void)userdata; // unused
free(ptr);
}
//...
sg_setup(&(sg_desc){
//...
.allocator = {
.alloc = my_malloc,
.free = my_free,
.user_data = ...,
}
});
```
sokol_gfx.h will now call ```my_malloc()``` and ```my_free()``` whenever it needs
to allocate or free memory (note however that allocations inside OS
functions or 3rd party libraries are not affected).
If no override functions are provided, the standard library functions ```malloc()``` and ```free()```
will be used, just as before.
This change breaks source compatibility in the following headers:
- **sokol_fontstash.h**: the function signature of ```sfons_create()``` has changed,
this now takes a pointer to a new ```sfons_desc_t``` struct instead of
individual parameters.
- **sokol_gfx_imgui.h** (NOT sokol_imgui.h!): likewise, the function signature of
```sg_imgui_init()``` has changed, this now takes an additional parameter
which is a pointer to a new ```sg_imgui_desc_t``` struct.
All affected headers also have a preprocessor check for the outdated
macros ```SOKOL_MALLOC```, ```SOKOL_CALLOC``` and ```SOKOL_FREE``` and throw
a compilation error if those macros are detected.
(if configuration through macros is still desired this could be added back in
the future, but I figured that the new way is more flexible in most situations).
The header sokol_memtrack.h and the sample [restart-sapp](https://floooh.github.io/sokol-html5/restart-sapp.html) have been updated accordingly.
Also search for ```MEMORY ALLOCATION OVERRIDE``` in the header documentation block
for more details.
- **14-May-2022**: added a helper function ```simgui_map_keycode()``` to
sokol_imgui.h to map sokol_app.h keycodes (```sapp_keycode```,
```SAPP_KEYCODE_*```) to Dear ImGui keycodes (```ImGuiKey```, ```ImGuiKey_*```).
If you're using Dear ImGui function to check for key input, you'll need to
- **KNOWN ISSUE**: the recent change in sokol-audio's WASAPI backend to directly consume
float samples doesn't appear to work on some configs (see [#614](https://github.com/floooh/sokol/issues/614)),
investigation is underway
- **15-Jan-2022**:
- A bugfix in the GL backend for uniform arrays using the 'native' uniform block layout.
The bug was a regression in the recent 'uniform data handling' update. See
[PR #611](https://github.com/floooh/sokol/pull/611) for details, and this [new sample/test](https://github.com/floooh/sokol-samples/blob/master/glfw/uniformarrays-glfw.c).
Many thanks to @nmr8acme for the PR!
- **08-Jan-2022**: some enhancements and cleanup to uniform data handling in sokol_gfx.h
and the sokol-shdc shader compiler:
- *IMPORTANT*: when updating sokol_gfx.h (and you're using the sokol-shdc shader compiler),
don't forget to update the sokol-shdc binaries too!
- The GLSL uniform types int, ivec2, ivec3 and
ivec4 can now be used in shader code, those are exposed to the GL
backends with the new ```sg_uniform_type``` items
```SG_UNIFORM_TYPE_INT[2,3,4]```.
- A new enum ```sg_uniform_layout```, currently with the values SG_UNIFORMLAYOUT_NATIVE
and SG_UNIFORMLAYOUT_STD140. The enum is used in ```sg_shader_uniform_block_desc```
as a 'packing rule hint', so that the GL backend can properly locate the offset
of uniform block members. The default (SG_UNIFORMLAYOUT_NATIVE) keeps the same
behaviour, so existing code shouldn't need to be changed. With the packing
rule SG_UNIFORMLAYOUT_STD140 the uniform block interior is expected to be
layed out according to the OpenGL std140 packing rule.
- Note that the SG_UNIFORMLAYOUT_STD140 only allows a subset of the actual std140
packing rule: arrays are only allowed for the types vec4, int4 and mat4.
This is because the uniform data must still be compatible with
```glUniform()``` calls in the GL backends (which have different
'interior alignment' for arrays).
- The sokol-shdc compiler supports the new uniform types and will annotate the
code-generated sg_shader_desc structs with SG_UNIFORMLAYOUT_STD140,
and there are new errors to make sure that uniform blocks are compatible
with all sokol_gfx.h backends.
- Likewise, sokol_gfx.h has tighter validation for the ```sg_shader_uniform_block```
desc struct, but only when the GL backend is used (in general, the interior
layout of uniform blocks is only relevant for GL backends, on all other backends
sokol_gfx.h just passes the uniform data as an opaque block to the shader)
For more details see:
- [new sections in the sokol_gfx.h documentation](https://github.com/floooh/sokol/blob/ba64add0b67cac16fc86fb6b64d1da5f67e80c0f/sokol_gfx.h#L343-L450)
- [documentation of ```sg_uniform_layout```](https://github.com/floooh/sokol/blob/ba64add0b67cac16fc86fb6b64d1da5f67e80c0f/sokol_gfx.h#L1322-L1355)
- **14-Feb-2021**: The Dear ImGui rendering backend in [sokol_imgui.h](https://github.com/floooh/sokol/blob/master/util/sokol_imgui.h) has been rewritten to only do a single
buffer-update per frame each for vertex- and index-data. This addresses performance-problems
with sg_append_buffer() in the GL backend on some platforms (see [this issue](https://github.com/floooh/sokol/issues/399) for details.
- **13-Feb-2021**: A new utility header [sokol_nuklear.h](https://github.com/floooh/sokol/blob/master/util/sokol_nuklear.h)
has been added which implements a rendering backend for [Nuklear](https://github.com/Immediate-Mode-UI/Nuklear)
on top of sokol_gfx.h. Also see the new sample [nuklear-sapp](https://floooh.github.io/sokol-html5/nuklear-sapp.html).
Many thanks to **@wmerrifield** for the PR!
- **10-Feb-2021**: The breaking API-update has been merged (mainly sokol_gfx.h).
Please see [this blogpost](https://floooh.github.io/2021/02/07/sokol-api-overhaul.html)
and the updates [sokol samples](https://floooh.github.io/sokol-html5/) for details.
I also created a git tag named 'pre-feb2021-api-changes' which captures the previous
state in all related projects. Please also update the [sokol-tools-bin](https://github.com/floooh/sokol-tools-bin) if you're using the sokol-shdc shader compiler.
- **07-Feb-2021**: A PSA about upcoming breaking changes in (mainly) sokol_gfx.h: https://floooh.github.io/2021/02/07/sokol-api-overhaul.html
- **20-Dec-2020**: A couple of minor breaking changes in the sokol_gfx.h and
sokol_app.h APIs as preparation for the upcoming automatic language binding
generation:
- in **sokol_gfx.h** nested unions have been removed:
- **sg_image_desc.depth/.layers** has been renamed to **.num_slices**
- **sg_attachment_desc.face/.layer/.slice** has been unified to **.slice**
- in **sokol_app.h** the return value of **sapp_run()** has been changed from
**int** to **void** (the function always returned zero anyway)
Non-breaking (or at most potentially breaking) changes:
- expressions in enums have been replaced with integer literals (e.g. (1<<2)becomes4)
- the value of **SAPP_MOUSEBUTTON_INVALID** has been changed from -1 to 0x100
For more information about the upcoming automatic language-bindings generation [see this bog post](https://floooh.github.io/2020/08/23/sokol-bindgen.html)
- **02-Dec-2020**: sokol_gfx.h has a couple new public API functions for
destroying resources in two steps:
- sg_uninit_buffer + sg_dealloc_buffer
- sg_uninit_image + sg_dealloc_image
- sg_uninit_shader + sg_dealloc_shader
- sg_uninit_pipeline + sg_dealloc_pipeline
- sg_uninit_pass + sg_dealloc_pass
Calling both functions in this order is identical with calling the
traditional sg_destroy_xxx() functions. See this PR for more details:
https://github.com/floooh/sokol/pull/435. Many thanks to @oviano for the
PR!
- **28-Nov-2020**: In addition to the generic SOKOL_API_DECL and SOKOL_IMPL
defines there are now header-specific versions SOKOL_xxx_API_DECL and
SOKOL_xxx_IMPL (for instance SOKOL_GFX_API_DECL and SOKOL_GFX_IMPL). The
original motivation for splitting the SOKOL_API_DECL defines up is described
here: https://github.com/floooh/sokol/issues/428). The same change for
SOKOL_IMPL also finally unifies the approach used in the utility headers (in
the ```util``` subdirectory), which exclusively used the SOKOL_xxx_IMPL
pattern with the core headers which exclusively used SOKOL_IMPL before (all
headers accept both patterns now). Many thanks to @iboB for providing the
API_DECL PR!
- **17-Nov-2020**: A new utility header **sokol_shape.h** to generate
vertices+indices for simple shapes (plane, box, sphere, cylinder and torus),
which seamlessly plug into the sokol_gfx.h resource creation functions. As
with most new utility headers, the initial functionality is a bit bare bones
and the public API shouldn't be considered stable yet. Check the sokol-samples
webpage for new and updates samples: https://floooh.github.io/sokol-html5/
- **08-Nov-2020** PSA: It appears that RenderDoc v1.10 chokes on the new
D3D11/DXGI swapchain code from 10-Oct-2020 in sokol_app.h. The current
RenderDoc Nightly Build works, so I guess in v1.11 everything will be fine.
- **03-Nov-2020**: sokol_app.h: the missing drag'n'drop support for HTML5/WASM
has been added. This adds two platform-specific functions
```sapp_html5_get_dropped_file_size()``` and
```sapp_html5_fetch_dropped_file()```. Please read the documentation
section in sokol_app.h under 'DRAG AND DROP SUPPORT' for additional
details and example code. Also consult the source code of the new
```droptest-sapp``` sample for an example of how to load the content
- sokol_app.h WASM: mouse wheel scroll deltas are now 'normalized' between
the different scroll modes (pixels, lines, pages). See this issue:
https://github.com/floooh/sokol/issues/339. Many thanks to @bqqbarbhg for
investigating the issue and providing a solution!
- sokol_app.h now has [better documentation](https://github.com/floooh/sokol/blob/89a3bb8da0a2df843d6cc60a270ddc69f9aa69d6/sokol_app.h#L70)
what system libraries must be linked on the various platforms (and on Linux two additional libraries must be
linked now: Xcursor and Xi)
- **22-Jul-2020**: **PLEASE NOTE** cmake 3.18 breaks some of sokol samples when
compiling with the Visual Studio toolchain because some C files now actually
compile as C++ for some reason (see:
https://twitter.com/FlohOfWoe/status/1285996526117040128). Until this is
fixed, or I have come up with a workaround, please use an older cmake version
to build the sokol samples with the Visual Studio compiler.
(Update: I have added a workaround to fips: https://github.com/floooh/fips/commit/89997b8ebdca6fc9455a5cfe6145eecaa017df49
which fixes the issue at least for fips projects)
- **14-Jul-2020**:
- sapp_mouse_shown() has been implemented for macOS (thanks to @slmjkdbtl for
providing the initial PR!)
- On macOS, the lower-level functions CGDisplayShowCursor and CGDisplayHideCursor
are now used instead of the NSCursor class. This is in preparation for the
'pointer lock' feature which will also use CGDisplay* functions.
- Calling ```sapp_show_mouse(bool visible)``` no longer 'stacks' (e.g. there's
no 'hidden counter' underneath anymore, instead calling ```sapp_show_mouse(true)```
will always show the cursor and ```sapp_show_mouse(false)``` will always
hide it. This is a different behaviour than the underlying Win32 and
macOS functions ShowCursor() and CGDisplaShow/HideCursor()
- The mouse show/hide behaviour can now be tested in the ```events-sapp``` sample
(so far this only works on Windows and macOS).
- **13-Jul-2020**:
- On macOS and iOS, sokol_app.h and sokol_gfx.h can now be compiled with
ARC (Automatic Reference Counting) **disabled** (previously ARC had to be
enabled).
- Compiling with ARC enabled is still supported but with a little caveat:
if you're compiling sokol_app.h or sokol_gfx.h in ObjC mode (not ObjC++
mode) *AND* ARC is enabled, then the Xcode version must be more recent
than before (the language feature ```__has_feature(objc_arc_fields)```
must be supported, which I think has been added in Xcode 10.2, I couldn't
find this mentioned in any Xcode release notes though). Compiling with
ARC disabled should also work on older Xcode versions though.
- Various internal code cleanup things:
- sokol_app.h had the same 'structural cleanup' as sokol_gfx.h in
January, all internal state (including ObjC id's) has been merged into
a single big state structure. Backend specific struct declarations
have been moved closer together in the header, and
backend-specific structures and functions have been named more
consistently for better 'searchability'
- The 'mini GL' loader in the sokol_app.h Win32+WGL backend has been
rewritten to use X-Macros (less redundant lines of code)
- All macOS and iOS code has been revised and cleaned up
- On macOS a workaround for a (what looks like) post-Catalina
NSOpenGLView issue has been added: if the sokol_app.h window doesn't
fit on screen (and was thus 'clamped' by Cocoa) *AND* the
content-size was not set to native Retina resolution, the initial
content size was reported as if it was in Retina resolution. This
caused an empty screen to be rendered in the imgui-sapp demo. The
workaround is to hook into the NSOpenGLView reshape event at which
point the reported content size is correct.
- On macOS and iOS, the various 'view delegate' objects have been
removed, and rendering happens instead in the subclasses of MTKView,
GLKView and NSOpenGLView.
- On macOS and iOS, there's now proper cleanup code in the
applicationWillTerminate callback (although note that on iOS this
function isn't guaranteed to be called, because an application can
also simply be killed by the operating system.
- **22-Jun-2020**: The X11/GLX backend in sokol_app.h now has (soft-)fullscreen
support, bringing the feature on par with Windows and macOS. Many thanks to
@medvednikov for the PR!
- **20-Jun-2020**: Some work to better support older DX10-level GPUs in the
sokol_gfx.h D3D11 backend:
- sg_make_shader() now by default compiles HLSL shader code as shader model 4.0
(previously shader model 5.0 which caused problems with some older
Intel GPUs still in use, see this issue: https://github.com/floooh/sokol/issues/179)
- A new string item ```const char* d3d11_target``` in ```sg_shader_stage_desc``` now allows
to pass in the D3D shader model for compiling shaders. This defaults to
"vs_4_0" for the vertex shader stage and "ps_4_0" for the fragment shader stage.
The minimal DX shader model for use with the sokol_gfx.h D3D11 backend is
shader model 4.0, because that's the first shader model supporting
constant buffers.
- The *sokol-shdc* shader compiler tool has a new output option ```hlsl4```
to generate HLSL4 source code and shader model 4.0 byte code.
- All embedded D3D shader byte code in the sokol utility headers has been
changed from shader model 5.0 to 4.0
If you are using sokol_gfx.h with sokol-shdc, please update both at the same time
to avoid compilation errors caused by the new ```sg_shader_stage_desc.d3d11_target```
item. The sg_shader_desc initialization code in sokol-shdc has now been made more
robust to prevent similar problems in the future.
- **14-Jun-2020**: I have added a very simple utility header ```sokol_memtrack.h```
which allows to track memory allocations in sokol headers (number and overall
size of allocations) by overriding the macros SOKOL_MALLOC, SOKOL_CALLOC and
SOKOL_FREE. Simply include ```sokol_memtrack.h``` before the other sokol
header implementation includes to enable memory tracking in those headers
(but remember that the sokol_memtrack.h implementation must only be included
once in the whole project, so this only works when all other sokol header
implementations are included in the same compilation unit).
- **06-Jun-2020**: Some optimizations in the sokol_gfx.h GL backend to avoid
redundant GL calls in two areas: in the sg_begin_pass() calls when not
clearing the color- and depth-stencil-attachments, and in sg_apply_bindings()
when binding textures. Everything should behave exactly as before, but if
you notice any problems in those areas, please file a bug. Many thanks to
@edubart for the PRs!
- **01-Jun-2020**: sokol_app.h now allows to toggle to and from fullscreen
programmatically and to query the current fullscreen state via 2 new
functions: ```sapp_toggle_fullscreen()``` and ```sapp_is_fullscreen()```.
Currently this is only implemented for Windows and macOS (not Linux).
Thanks to @mattiasljungstrom for getting the feature started and providing
the Win32 implementation!
- **28-May-2020**: a small quality-of-life improvement for C++ coders: when the
sokol headers are included into C++, all public API functions which take a
pointer to a struct now have a C++ overload which instead takes a const-ref.
This allows to move the struct initialization right into the function call
just like in C99. For instance, in C99 one can write:
```c
sg_buffer buf = sg_make_buffer(&(sg_buffer_desc){
.size = sizeof(vertices),
.type = SG_BUFFERTYPE_VERTEXBUFFER,
.content = vertices
});
```
In C++ it isn't possible to take the address of an 'adhoc-initialized'
struct like this, but with the new reference-wrapper functions (and C++20
designated initialization) this should work now:
```cpp
sg_buffer buf = sg_make_buffer({
.size = sizeof(vertices),
.type = SG_BUFFERTYPE_VERTEXBUFFER,
.content = vertices
});
```
Many thanks to @garettbass for providing the PR!
- **27-May-2020**: a new utility header [sokol_debugtext.h](https://github.com/floooh/sokol/blob/master/util/sokol_debugtext.h)
for rendering simple ASCII text using vintage home computer fonts via sokol_gfx.h
- **13-May-2020**: a new function in sokol_time.h to round a measured frame time
to common display refresh rates: ```stm_round_to_common_refresh_rate()```.
See the header documentation for the motivation behind this function.
- **02-May-2020**: sokol_app.h: the 'programmatic quit' behaviour on the
web-platform is now more in line with other platforms: calling
```sapp_quit()``` will invoke the cleanup callback function, perform
platform-specific cleanup (like unregistering JS event handlers), and finally
exit the frame loop. In typical scenarios this isn't very useful (because
usually the user will simply close the tab, which doesn't allow to run
cleanup code), but it's useful for situations where the same
code needs to run repeatedly on a web page. Many thanks to @caiiiycuk
for providing the PR!
- **30-Apr-2020**: experimental WebGPU backend and a minor breaking change:
- sokol_gfx.h: a new WebGPU backend, expect frequent breakage for a while
because the WebGPU API is still in flux
- a new header sokol_glue.h, with interop helper functions when specific combinations
of sokol headers are used together
- changes in the way sokol_gfx.h is initialized via a new layout of the
sg_desc structure
- sokol_gfx.h: a new ```sg_sampler_type``` enum which is required for
shader creation to tell the WebGPU backend about the sampler data types
(float, signed int, or unsigned int) used in the shader
- sokol_app.h: a handful new functions to query default framebuffer attributes (color- and
depth-buffer pixel formats, and MSAA sample count)
- sokol_app.h: WebGPU device and swapchain initialization (currently only
in the emscripten code path)
- [sokol-shdc](https://github.com/floooh/sokol-tools/blob/master/docs/sokol-shdc.md) has
been updated with WebGPU support (currently outputs SPIRV bytecode), and to output the new
```sg_sampler_type``` enum in ```sg_shader_image_desc```
- [sokol-samples](https://github.com/floooh/sokol-samples/) has a new set of
backend-specific WebGPU samples, and the other samples have been updated
for the new sokol-gfx initialization
- ```pre-webgpu``` tags have been added to the [sokol](https://github.com/floooh/sokol/releases/tag/pre-webgpu), [sokol-samples](https://github.com/floooh/sokol-samples/releases/tag/pre-webgpu), [sokol-tools](https://github.com/floooh/sokol-tools/releases/tag/pre-webgpu)
and [sokol-tools-bin](https://github.com/floooh/sokol-tools-bin/releases/tag/pre-webgpu) github repositories (in case you need to continue working with
the older versions)
- please see this [blog post](https://floooh.github.io/2020/04/26/sokol-spring-2020-update.html)
for more details
- **05-Apr-2020**: A bugfix in sokol_gl.h, the (fairly recent) optimization for
merging draw calls contained a bug that could be triggered in an "empty"
sgl_begin/sgl_end pair (with no vertices recorded inbetween). This could
lead to the following draw call being rendered with the wrong uniform data.
- **30-Jan-2020**: Some cleanup in sokol_gfx.h in the backend implementation code,
internal data structures and documentation comments. The public
API hasn't changed, so the change should be completely invisible
from the outside.
- **02-Dec-2019**: Initial clipboard support in sokol_app.h for Windows, macOS
and HTML5. This allows to read and write UTF-8 encoded strings from and
to the target platform's shared clipboard.
A 'real-world' example usage is in the [Visual6502 Remix project](https://github.com/floooh/v6502r).
Unfortunately clipboard support on the HTML5 platform comes with a lot of
platform-specific caveats which can't be solved in sokol_app.h alone
because of the restrictions the web platform puts on clipboard access and
different behaviours and support levels of the various HTML5 clipboard
APIs. I'm not really happy with the current HTML5 clipboard
implementation. It sorta works, but it sure ain't pretty :)
Maybe the situation will improve in a few years when all browsers agree
on and support the new [permission-based clipboard
These functions take a pointer to a resource creation desc struct that
may contain zero-initialized values (to indicate default values) and
return a new struct where the zero-init values have been replaced with
concrete values. This is useful to inspect the actual creation attributes
of a resource.
- **18-Aug-2019**:
- Pixelformat and runtime capabilities modernization in sokol_gfx.h (breaking changes):
- The list of pixel formats supported in sokol_gfx.h has been modernized,
many new formats are available, and some formats have been removed. The
supported pixel formats are now identical with what WebGPU provides,
minus the SRGB formats (if SRGB conversion is needed it should be done
in the pixel shader)
- The pixel format list is now more "orthogonal":
- one, two or four color components (R, RG, RGBA)
- 8-, 16- or 32-bit component width
- unsigned-normalized (no postfix), signed-normalized (SN postfix),
unsigned-integer (UI postfix) and signed-integer (SI postfix)
and float (F postfix) component types.
- special pixel formats BGRA8 (default render target format on
Metal and D3D11), RGB10A2 and RG11B10F
- DXT compressed formats replaced with BC1 to BC7 (BC1 to BC3
are identical to the old DXT pixel formats)
- packed 16-bit formats (like RGBA4) have been removed
- packed 24-bit formats (RGB8) have been removed
- Use the new function ```sg_query_pixelformat()``` to get detailed
runtime capability information about a pixelformat (for instance
whether it is supported at all, can be used as render target etc...).
- Use the new function ```sg_query_limits()``` to query "numeric limits"
like maximum texture dimensions for different texture types.
- The enumeration ```sg_feature``` and the function ```sg_query_feature()```
has been replaced with the new function ```sg_query_features()```, which
returns a struct ```sg_features``` (this contains a bool for each
optional feature).
- The default pixelformat for render target images and pipeline objects
now depends on the backend:
- for GL backends, the default pixelformat stays the same: RGBA8
- for the Metal and D3D11 backends, the default pixelformat for
render target images is now BGRA8 (the reason is because
MTKView's pixelformat was always BGRA8 but this was "hidden"
through an internal hack, and a BGRA swapchain is more efficient
than RGBA in D3D11/DXGI)
- Because of the above RGBA/BGRA change, you may see pixelformat validation
errors in existing code if the code assumes that a render target image is
always created with a default pixelformat of RGBA8.
- Changes in sokol_app.h:
- The D3D11 backend now creates the DXGI swapchain with BGRA8 pixelformat
(previously: RGBA8), this allows more efficient presentation in some
situations since no format-conversion-blit needs to happen.
- **18-Jul-2019**:
- sokol_fetch.h has been fixed and can be used again :)
- **11-Jul-2019**:
- Don't use sokol_fetch.h for now, the current version assumes that
it is possible to obtain the content size of a file from the
HTTP server without downloading the entire file first. Turns out
that's not possible with vanilla HTTP when the web server serves
files compressed (in that case the Content-Length is the _compressed_
size, yet JS/WASM only has access to the uncompressed data).
Long story short, I need to go back to the drawing board :)
- **06-Jul-2019**:
- new header [sokol_fetch.h](https://github.com/floooh/sokol/blob/master/sokol_fetch.h) for asynchronously loading data.
- make sure to carefully read the embedded documentation
for making the best use of the header
- two new samples: [simple PNG file loadng with stb_image.h](https://floooh.github.io/sokol-html5/loadpng-sapp.html) and [MPEG1 streaming with pl_mpeg.h](https://floooh.github.io/sokol-html5/plmpeg-sapp.html)
