sokol_nuklear.h -- drop-in Nuklear renderer/event-handler for sokol_gfx.h
Project URL: https://github.com/floooh/sokol
Do this: #define SOKOL_IMPL or #define SOKOL_NUKLEAR_IMPL
before you include this file in one C or C++ file to create the implementation.
The following defines are used by the implementation to select the platform-specific embedded shader code (these are the same defines as used by sokol_gfx.h and sokol_app.h):
SOKOL_GLCORE33 SOKOL_GLES2 SOKOL_GLES3 SOKOL_D3D11 SOKOL_METAL SOKOL_WGPU
Optionally provide the following configuration defines before including the implementation:
SOKOL_NUKLEAR_NO_SOKOL_APP - don't depend on sokol_app.h (see below for details)
Optionally provide the following macros before including the implementation to override defaults:
SOKOL_ASSERT(c) - your own assert macro (default: assert(c)) SOKOL_NUKLEAR_API_DECL- public function declaration prefix (default: extern) SOKOL_API_DECL - same as SOKOL_NUKLEAR_API_DECL SOKOL_API_IMPL - public function implementation prefix (default: -)
If sokol_nuklear.h is compiled as a DLL, define the following before including the declaration or implementation:
On Windows, SOKOL_DLL will define SOKOL_NUKLEAR_API_DECL as __declspec(dllexport) or __declspec(dllimport) as needed.
Include the following headers before sokol_nuklear.h (both before including the declaration and implementation):
sokol_gfx.h sokol_app.h (except SOKOL_NUKLEAR_NO_SOKOL_APP)
Additionally, include the following headers before including the implementation:
NOTE: Unlike most other sokol-headers, the implementation must be compiled as C, compiling as C++ isn't supported. The interface is callable from C++ of course.
sokol_nuklear.h implements the initialization, rendering and event-handling code for Nuklear (https://github.com/Immediate-Mode-UI/Nuklear) on top of sokol_gfx.h and (optionally) sokol_app.h.
The sokol_app.h dependency is optional and used for input event handling. If you only use sokol_gfx.h but not sokol_app.h in your application, define SOKOL_NUKLEAR_NO_SOKOL_APP before including the implementation of sokol_nuklear.h, this will remove any dependency to sokol_app.h, but you must feed input events into Nuklear yourself.
sokol_nuklear.h is not thread-safe, all calls must be made from the same thread where sokol_gfx.h is running.
--- To initialize sokol-nuklear, call:
snk_setup(const snk_desc_t* desc) This will initialize Nuklear and create sokol-gfx resources (two buffers for vertices and indices, a font texture and a pipeline- state-object). Use the following snk_desc_t members to configure behaviour: int max_vertices The maximum number of vertices used for UI rendering, default is 65536. sokol-nuklear will use this to compute the size of the vertex- and index-buffers allocated via sokol_gfx.h sg_pixel_format color_format The color pixel format of the render pass where the UI will be rendered. The default is SG_PIXELFORMAT_RGBA8 sg_pixel_format depth_format The depth-buffer pixel format of the render pass where the UI will be rendered. The default is SG_PIXELFORMAT_DEPTHSTENCIL. int sample_count The MSAA sample-count of the render pass where the UI will be rendered. The default is 1. float dpi_scale DPI scaling factor. Set this to the result of sapp_dpi_scale(). To render in high resolution on a Retina Mac this would typically be 2.0. The default value is 1.0 bool no_default_font Set this to true if you don't want to use Nuklear's default font. In this case you need to initialize the font yourself after snk_setup() is called.
--- At the start of a frame, call:
struct nk_context *snk_new_frame() This updates Nuklear's event handling state and then returns a Nuklear context pointer which you use to build the UI. For example: struct nk_context *ctx = snk_new_frame(); if (nk_begin(ctx, "Demo", nk_rect(50, 50, 200, 200), ...
--- at the end of the frame, before the sg_end_pass() where you want to render the UI, call:
snk_render(int width, int height) where 'width' and 'height' are the dimensions of the rendering surface. For example, if you're using sokol_app.h and render to the default framebuffer: snk_render(sapp_width(), sapp_height()); This will convert Nuklear's command list into a vertex and index buffer, and then render that through sokol_gfx.h
--- if you're using sokol_app.h, from inside the sokol_app.h event callback, call:
void snk_handle_event(const sapp_event* ev);
--- finally, on application shutdown, call
--- Note that for touch-based systems, like iOS, there is a wrapper around nk_edit_string(...), called snk_edit_string(...) which will show and hide the onscreen keyboard as required.
Copyright (c) 2020 Warren Merrifield
This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 3. This notice may not be removed or altered from any source distribution.