-
Notifications
You must be signed in to change notification settings - Fork 598
/
Copy pathnuklear.h
5824 lines (5408 loc) · 239 KB
/
nuklear.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/** \file nuklear.h
* \brief main API and documentation file
*
* \details
*/
#ifndef NK_NUKLEAR_H_
#define NK_NUKLEAR_H_
#ifdef __cplusplus
extern "C" {
#endif
/*
* ==============================================================
*
* CONSTANTS
*
* ===============================================================
*/
#define NK_UNDEFINED (-1.0f)
#define NK_UTF_INVALID 0xFFFD /**< internal invalid utf8 rune */
#define NK_UTF_SIZE 4 /**< describes the number of bytes a glyph consists of*/
#ifndef NK_INPUT_MAX
#define NK_INPUT_MAX 16
#endif
#ifndef NK_MAX_NUMBER_BUFFER
#define NK_MAX_NUMBER_BUFFER 64
#endif
#ifndef NK_SCROLLBAR_HIDING_TIMEOUT
#define NK_SCROLLBAR_HIDING_TIMEOUT 4.0f
#endif
/*
* ==============================================================
*
* HELPER
*
* ===============================================================
*/
#ifndef NK_API
#ifdef NK_PRIVATE
#if (defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199409L))
#define NK_API static inline
#elif defined(__cplusplus)
#define NK_API static inline
#else
#define NK_API static
#endif
#else
#define NK_API extern
#endif
#endif
#ifndef NK_LIB
#ifdef NK_SINGLE_FILE
#define NK_LIB static
#else
#define NK_LIB extern
#endif
#endif
#define NK_INTERN static
#define NK_STORAGE static
#define NK_GLOBAL static
#define NK_FLAG(x) (1 << (x))
#define NK_STRINGIFY(x) #x
#define NK_MACRO_STRINGIFY(x) NK_STRINGIFY(x)
#define NK_STRING_JOIN_IMMEDIATE(arg1, arg2) arg1 ## arg2
#define NK_STRING_JOIN_DELAY(arg1, arg2) NK_STRING_JOIN_IMMEDIATE(arg1, arg2)
#define NK_STRING_JOIN(arg1, arg2) NK_STRING_JOIN_DELAY(arg1, arg2)
#ifdef _MSC_VER
#define NK_UNIQUE_NAME(name) NK_STRING_JOIN(name,__COUNTER__)
#else
#define NK_UNIQUE_NAME(name) NK_STRING_JOIN(name,__LINE__)
#endif
#ifndef NK_STATIC_ASSERT
#define NK_STATIC_ASSERT(exp) typedef char NK_UNIQUE_NAME(_dummy_array)[(exp)?1:-1]
#endif
#ifndef NK_FILE_LINE
#ifdef _MSC_VER
#define NK_FILE_LINE __FILE__ ":" NK_MACRO_STRINGIFY(__COUNTER__)
#else
#define NK_FILE_LINE __FILE__ ":" NK_MACRO_STRINGIFY(__LINE__)
#endif
#endif
#define NK_MIN(a,b) ((a) < (b) ? (a) : (b))
#define NK_MAX(a,b) ((a) < (b) ? (b) : (a))
#define NK_CLAMP(i,v,x) (NK_MAX(NK_MIN(v,x), i))
#ifdef NK_INCLUDE_STANDARD_VARARGS
#include <stdarg.h>
#if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */
#include <sal.h>
#define NK_PRINTF_FORMAT_STRING _Printf_format_string_
#else
#define NK_PRINTF_FORMAT_STRING
#endif
#if defined(__GNUC__)
#define NK_PRINTF_VARARG_FUNC(fmtargnumber) __attribute__((format(__printf__, fmtargnumber, fmtargnumber+1)))
#define NK_PRINTF_VALIST_FUNC(fmtargnumber) __attribute__((format(__printf__, fmtargnumber, 0)))
#else
#define NK_PRINTF_VARARG_FUNC(fmtargnumber)
#define NK_PRINTF_VALIST_FUNC(fmtargnumber)
#endif
#endif
/*
* ===============================================================
*
* BASIC
*
* ===============================================================
*/
#ifdef NK_INCLUDE_FIXED_TYPES
#include <stdint.h>
#define NK_INT8 int8_t
#define NK_UINT8 uint8_t
#define NK_INT16 int16_t
#define NK_UINT16 uint16_t
#define NK_INT32 int32_t
#define NK_UINT32 uint32_t
#define NK_SIZE_TYPE uintptr_t
#define NK_POINTER_TYPE uintptr_t
#else
#ifndef NK_INT8
#define NK_INT8 signed char
#endif
#ifndef NK_UINT8
#define NK_UINT8 unsigned char
#endif
#ifndef NK_INT16
#define NK_INT16 signed short
#endif
#ifndef NK_UINT16
#define NK_UINT16 unsigned short
#endif
#ifndef NK_INT32
#if defined(_MSC_VER)
#define NK_INT32 __int32
#else
#define NK_INT32 signed int
#endif
#endif
#ifndef NK_UINT32
#if defined(_MSC_VER)
#define NK_UINT32 unsigned __int32
#else
#define NK_UINT32 unsigned int
#endif
#endif
#ifndef NK_SIZE_TYPE
#if defined(_WIN64) && defined(_MSC_VER)
#define NK_SIZE_TYPE unsigned __int64
#elif (defined(_WIN32) || defined(WIN32)) && defined(_MSC_VER)
#define NK_SIZE_TYPE unsigned __int32
#elif defined(__GNUC__) || defined(__clang__)
#if defined(__x86_64__) || defined(__ppc64__) || defined(__PPC64__) || defined(__aarch64__)
#define NK_SIZE_TYPE unsigned long
#else
#define NK_SIZE_TYPE unsigned int
#endif
#else
#define NK_SIZE_TYPE unsigned long
#endif
#endif
#ifndef NK_POINTER_TYPE
#if defined(_WIN64) && defined(_MSC_VER)
#define NK_POINTER_TYPE unsigned __int64
#elif (defined(_WIN32) || defined(WIN32)) && defined(_MSC_VER)
#define NK_POINTER_TYPE unsigned __int32
#elif defined(__GNUC__) || defined(__clang__)
#if defined(__x86_64__) || defined(__ppc64__) || defined(__PPC64__) || defined(__aarch64__)
#define NK_POINTER_TYPE unsigned long
#else
#define NK_POINTER_TYPE unsigned int
#endif
#else
#define NK_POINTER_TYPE unsigned long
#endif
#endif
#endif
#ifndef NK_BOOL
#ifdef NK_INCLUDE_STANDARD_BOOL
#include <stdbool.h>
#define NK_BOOL bool
#else
#define NK_BOOL int /**< could be char, use int for drop-in replacement backwards compatibility */
#endif
#endif
typedef NK_INT8 nk_char;
typedef NK_UINT8 nk_uchar;
typedef NK_UINT8 nk_byte;
typedef NK_INT16 nk_short;
typedef NK_UINT16 nk_ushort;
typedef NK_INT32 nk_int;
typedef NK_UINT32 nk_uint;
typedef NK_SIZE_TYPE nk_size;
typedef NK_POINTER_TYPE nk_ptr;
typedef NK_BOOL nk_bool;
typedef nk_uint nk_hash;
typedef nk_uint nk_flags;
typedef nk_uint nk_rune;
/* Make sure correct type size:
* This will fire with a negative subscript error if the type sizes
* are set incorrectly by the compiler, and compile out if not */
NK_STATIC_ASSERT(sizeof(nk_short) == 2);
NK_STATIC_ASSERT(sizeof(nk_ushort) == 2);
NK_STATIC_ASSERT(sizeof(nk_uint) == 4);
NK_STATIC_ASSERT(sizeof(nk_int) == 4);
NK_STATIC_ASSERT(sizeof(nk_byte) == 1);
NK_STATIC_ASSERT(sizeof(nk_flags) >= 4);
NK_STATIC_ASSERT(sizeof(nk_rune) >= 4);
NK_STATIC_ASSERT(sizeof(nk_size) >= sizeof(void*));
NK_STATIC_ASSERT(sizeof(nk_ptr) >= sizeof(void*));
#ifdef NK_INCLUDE_STANDARD_BOOL
NK_STATIC_ASSERT(sizeof(nk_bool) == sizeof(bool));
#else
NK_STATIC_ASSERT(sizeof(nk_bool) >= 2);
#endif
/* ============================================================================
*
* API
*
* =========================================================================== */
struct nk_buffer;
struct nk_allocator;
struct nk_command_buffer;
struct nk_draw_command;
struct nk_convert_config;
struct nk_style_item;
struct nk_text_edit;
struct nk_draw_list;
struct nk_user_font;
struct nk_panel;
struct nk_context;
struct nk_draw_vertex_layout_element;
struct nk_style_button;
struct nk_style_toggle;
struct nk_style_selectable;
struct nk_style_slide;
struct nk_style_progress;
struct nk_style_scrollbar;
struct nk_style_edit;
struct nk_style_property;
struct nk_style_chart;
struct nk_style_combo;
struct nk_style_tab;
struct nk_style_window_header;
struct nk_style_window;
enum {nk_false, nk_true};
struct nk_color {nk_byte r,g,b,a;};
struct nk_colorf {float r,g,b,a;};
struct nk_vec2 {float x,y;};
struct nk_vec2i {short x, y;};
struct nk_rect {float x,y,w,h;};
struct nk_recti {short x,y,w,h;};
typedef char nk_glyph[NK_UTF_SIZE];
typedef union {void *ptr; int id;} nk_handle;
struct nk_image {nk_handle handle; nk_ushort w, h; nk_ushort region[4];};
struct nk_nine_slice {struct nk_image img; nk_ushort l, t, r, b;};
struct nk_cursor {struct nk_image img; struct nk_vec2 size, offset;};
struct nk_scroll {nk_uint x, y;};
enum nk_heading {NK_UP, NK_RIGHT, NK_DOWN, NK_LEFT};
enum nk_button_behavior {NK_BUTTON_DEFAULT, NK_BUTTON_REPEATER};
enum nk_modify {NK_FIXED = nk_false, NK_MODIFIABLE = nk_true};
enum nk_orientation {NK_VERTICAL, NK_HORIZONTAL};
enum nk_collapse_states {NK_MINIMIZED = nk_false, NK_MAXIMIZED = nk_true};
enum nk_show_states {NK_HIDDEN = nk_false, NK_SHOWN = nk_true};
enum nk_chart_type {NK_CHART_LINES, NK_CHART_COLUMN, NK_CHART_MAX};
enum nk_chart_event {NK_CHART_HOVERING = 0x01, NK_CHART_CLICKED = 0x02};
enum nk_color_format {NK_RGB, NK_RGBA};
enum nk_popup_type {NK_POPUP_STATIC, NK_POPUP_DYNAMIC};
enum nk_layout_format {NK_DYNAMIC, NK_STATIC};
enum nk_tree_type {NK_TREE_NODE, NK_TREE_TAB};
typedef void*(*nk_plugin_alloc)(nk_handle, void *old, nk_size);
typedef void (*nk_plugin_free)(nk_handle, void *old);
typedef nk_bool(*nk_plugin_filter)(const struct nk_text_edit*, nk_rune unicode);
typedef void(*nk_plugin_paste)(nk_handle, struct nk_text_edit*);
typedef void(*nk_plugin_copy)(nk_handle, const char*, int len);
struct nk_allocator {
nk_handle userdata;
nk_plugin_alloc alloc;
nk_plugin_free free;
};
enum nk_symbol_type {
NK_SYMBOL_NONE,
NK_SYMBOL_X,
NK_SYMBOL_UNDERSCORE,
NK_SYMBOL_CIRCLE_SOLID,
NK_SYMBOL_CIRCLE_OUTLINE,
NK_SYMBOL_RECT_SOLID,
NK_SYMBOL_RECT_OUTLINE,
NK_SYMBOL_TRIANGLE_UP,
NK_SYMBOL_TRIANGLE_DOWN,
NK_SYMBOL_TRIANGLE_LEFT,
NK_SYMBOL_TRIANGLE_RIGHT,
NK_SYMBOL_PLUS,
NK_SYMBOL_MINUS,
NK_SYMBOL_TRIANGLE_UP_OUTLINE,
NK_SYMBOL_TRIANGLE_DOWN_OUTLINE,
NK_SYMBOL_TRIANGLE_LEFT_OUTLINE,
NK_SYMBOL_TRIANGLE_RIGHT_OUTLINE,
NK_SYMBOL_MAX
};
/* =============================================================================
*
* CONTEXT
*
* =============================================================================*/
/**
* \page Context
* Contexts are the main entry point and the majestro of nuklear and contain all required state.
* They are used for window, memory, input, style, stack, commands and time management and need
* to be passed into all nuklear GUI specific functions.
*
* # Usage
* To use a context it first has to be initialized which can be achieved by calling
* one of either `nk_init_default`, `nk_init_fixed`, `nk_init`, `nk_init_custom`.
* Each takes in a font handle and a specific way of handling memory. Memory control
* hereby ranges from standard library to just specifying a fixed sized block of memory
* which nuklear has to manage itself from.
*
* ```c
* struct nk_context ctx;
* nk_init_xxx(&ctx, ...);
* while (1) {
* // [...]
* nk_clear(&ctx);
* }
* nk_free(&ctx);
* ```
*
* # Reference
* Function | Description
* --------------------|-------------------------------------------------------
* \ref nk_init_default | Initializes context with standard library memory allocation (malloc,free)
* \ref nk_init_fixed | Initializes context from single fixed size memory block
* \ref nk_init | Initializes context with memory allocator callbacks for alloc and free
* \ref nk_init_custom | Initializes context from two buffers. One for draw commands the other for window/panel/table allocations
* \ref nk_clear | Called at the end of the frame to reset and prepare the context for the next frame
* \ref nk_free | Shutdown and free all memory allocated inside the context
* \ref nk_set_user_data| Utility function to pass user data to draw command
*/
#ifdef NK_INCLUDE_DEFAULT_ALLOCATOR
/**
* # nk_init_default
* Initializes a `nk_context` struct with a default standard library allocator.
* Should be used if you don't want to be bothered with memory management in nuklear.
*
* ```c
* nk_bool nk_init_default(struct nk_context *ctx, const struct nk_user_font *font);
* ```
*
* Parameter | Description
* ------------|---------------------------------------------------------------
* \param[in] ctx | Must point to an either stack or heap allocated `nk_context` struct
* \param[in] font | Must point to a previously initialized font handle for more info look at font documentation
*
* \returns either `false(0)` on failure or `true(1)` on success.
*/
NK_API nk_bool nk_init_default(struct nk_context*, const struct nk_user_font*);
#endif
/**
* # nk_init_fixed
* Initializes a `nk_context` struct from single fixed size memory block
* Should be used if you want complete control over nuklear's memory management.
* Especially recommended for system with little memory or systems with virtual memory.
* For the later case you can just allocate for example 16MB of virtual memory
* and only the required amount of memory will actually be committed.
*
* ```c
* nk_bool nk_init_fixed(struct nk_context *ctx, void *memory, nk_size size, const struct nk_user_font *font);
* ```
*
* !!! Warning
* make sure the passed memory block is aligned correctly for `nk_draw_commands`.
*
* Parameter | Description
* ------------|--------------------------------------------------------------
* \param[in] ctx | Must point to an either stack or heap allocated `nk_context` struct
* \param[in] memory | Must point to a previously allocated memory block
* \param[in] size | Must contain the total size of memory
* \param[in] font | Must point to a previously initialized font handle for more info look at font documentation
*
* \returns either `false(0)` on failure or `true(1)` on success.
*/
NK_API nk_bool nk_init_fixed(struct nk_context*, void *memory, nk_size size, const struct nk_user_font*);
/**
* # nk_init
* Initializes a `nk_context` struct with memory allocation callbacks for nuklear to allocate
* memory from. Used internally for `nk_init_default` and provides a kitchen sink allocation
* interface to nuklear. Can be useful for cases like monitoring memory consumption.
*
* ```c
* nk_bool nk_init(struct nk_context *ctx, const struct nk_allocator *alloc, const struct nk_user_font *font);
* ```
*
* Parameter | Description
* ------------|---------------------------------------------------------------
* \param[in] ctx | Must point to an either stack or heap allocated `nk_context` struct
* \param[in] alloc | Must point to a previously allocated memory allocator
* \param[in] font | Must point to a previously initialized font handle for more info look at font documentation
*
* \returns either `false(0)` on failure or `true(1)` on success.
*/
NK_API nk_bool nk_init(struct nk_context*, const struct nk_allocator*, const struct nk_user_font*);
/**
* \brief Initializes a `nk_context` struct from two different either fixed or growing buffers.
*
* \details
* The first buffer is for allocating draw commands while the second buffer is
* used for allocating windows, panels and state tables.
*
* ```c
* nk_bool nk_init_custom(struct nk_context *ctx, struct nk_buffer *cmds, struct nk_buffer *pool, const struct nk_user_font *font);
* ```
*
* \param[in] ctx Must point to an either stack or heap allocated `nk_context` struct
* \param[in] cmds Must point to a previously initialized memory buffer either fixed or dynamic to store draw commands into
* \param[in] pool Must point to a previously initialized memory buffer either fixed or dynamic to store windows, panels and tables
* \param[in] font Must point to a previously initialized font handle for more info look at font documentation
*
* \returns either `false(0)` on failure or `true(1)` on success.
*/
NK_API nk_bool nk_init_custom(struct nk_context*, struct nk_buffer *cmds, struct nk_buffer *pool, const struct nk_user_font*);
/**
* \brief Resets the context state at the end of the frame.
*
* \details
* This includes mostly garbage collector tasks like removing windows or table
* not called and therefore used anymore.
*
* ```c
* void nk_clear(struct nk_context *ctx);
* ```
*
* \param[in] ctx Must point to a previously initialized `nk_context` struct
*/
NK_API void nk_clear(struct nk_context*);
/**
* \brief Frees all memory allocated by nuklear; Not needed if context was initialized with `nk_init_fixed`.
*
* \details
* ```c
* void nk_free(struct nk_context *ctx);
* ```
*
* \param[in] ctx Must point to a previously initialized `nk_context` struct
*/
NK_API void nk_free(struct nk_context*);
#ifdef NK_INCLUDE_COMMAND_USERDATA
/**
* \brief Sets the currently passed userdata passed down into each draw command.
*
* \details
* ```c
* void nk_set_user_data(struct nk_context *ctx, nk_handle data);
* ```
*
* \param[in] ctx Must point to a previously initialized `nk_context` struct
* \param[in] data Handle with either pointer or index to be passed into every draw commands
*/
NK_API void nk_set_user_data(struct nk_context*, nk_handle handle);
#endif
/* =============================================================================
*
* INPUT
*
* =============================================================================*/
/**
* \page Input
*
* The input API is responsible for holding the current input state composed of
* mouse, key and text input states.
* It is worth noting that no direct OS or window handling is done in nuklear.
* Instead all input state has to be provided by platform specific code. This on one hand
* expects more work from the user and complicates usage but on the other hand
* provides simple abstraction over a big number of platforms, libraries and other
* already provided functionality.
*
* ```c
* nk_input_begin(&ctx);
* while (GetEvent(&evt)) {
* if (evt.type == MOUSE_MOVE)
* nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
* else if (evt.type == [...]) {
* // [...]
* }
* } nk_input_end(&ctx);
* ```
*
* # Usage
* Input state needs to be provided to nuklear by first calling `nk_input_begin`
* which resets internal state like delta mouse position and button transitions.
* After `nk_input_begin` all current input state needs to be provided. This includes
* mouse motion, button and key pressed and released, text input and scrolling.
* Both event- or state-based input handling are supported by this API
* and should work without problems. Finally after all input state has been
* mirrored `nk_input_end` needs to be called to finish input process.
*
* ```c
* struct nk_context ctx;
* nk_init_xxx(&ctx, ...);
* while (1) {
* Event evt;
* nk_input_begin(&ctx);
* while (GetEvent(&evt)) {
* if (evt.type == MOUSE_MOVE)
* nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
* else if (evt.type == [...]) {
* // [...]
* }
* }
* nk_input_end(&ctx);
* // [...]
* nk_clear(&ctx);
* } nk_free(&ctx);
* ```
*
* # Reference
* Function | Description
* --------------------|-------------------------------------------------------
* \ref nk_input_begin | Begins the input mirroring process. Needs to be called before all other `nk_input_xxx` calls
* \ref nk_input_motion | Mirrors mouse cursor position
* \ref nk_input_key | Mirrors key state with either pressed or released
* \ref nk_input_button | Mirrors mouse button state with either pressed or released
* \ref nk_input_scroll | Mirrors mouse scroll values
* \ref nk_input_char | Adds a single ASCII text character into an internal text buffer
* \ref nk_input_glyph | Adds a single multi-byte UTF-8 character into an internal text buffer
* \ref nk_input_unicode| Adds a single unicode rune into an internal text buffer
* \ref nk_input_end | Ends the input mirroring process by calculating state changes. Don't call any `nk_input_xxx` function referenced above after this call
*/
enum nk_keys {
NK_KEY_NONE,
NK_KEY_SHIFT,
NK_KEY_CTRL,
NK_KEY_DEL,
NK_KEY_ENTER,
NK_KEY_TAB,
NK_KEY_BACKSPACE,
NK_KEY_COPY,
NK_KEY_CUT,
NK_KEY_PASTE,
NK_KEY_UP,
NK_KEY_DOWN,
NK_KEY_LEFT,
NK_KEY_RIGHT,
/* Shortcuts: text field */
NK_KEY_TEXT_INSERT_MODE,
NK_KEY_TEXT_REPLACE_MODE,
NK_KEY_TEXT_RESET_MODE,
NK_KEY_TEXT_LINE_START,
NK_KEY_TEXT_LINE_END,
NK_KEY_TEXT_START,
NK_KEY_TEXT_END,
NK_KEY_TEXT_UNDO,
NK_KEY_TEXT_REDO,
NK_KEY_TEXT_SELECT_ALL,
NK_KEY_TEXT_WORD_LEFT,
NK_KEY_TEXT_WORD_RIGHT,
/* Shortcuts: scrollbar */
NK_KEY_SCROLL_START,
NK_KEY_SCROLL_END,
NK_KEY_SCROLL_DOWN,
NK_KEY_SCROLL_UP,
NK_KEY_MAX
};
enum nk_buttons {
NK_BUTTON_LEFT,
NK_BUTTON_MIDDLE,
NK_BUTTON_RIGHT,
NK_BUTTON_DOUBLE,
NK_BUTTON_MAX
};
/**
* \brief Begins the input mirroring process by resetting text, scroll
* mouse, previous mouse position and movement as well as key state transitions.
*
* \details
* ```c
* void nk_input_begin(struct nk_context*);
* ```
*
* \param[in] ctx Must point to a previously initialized `nk_context` struct
*/
NK_API void nk_input_begin(struct nk_context*);
/**
* \brief Mirrors current mouse position to nuklear
*
* \details
* ```c
* void nk_input_motion(struct nk_context *ctx, int x, int y);
* ```
*
* \param[in] ctx Must point to a previously initialized `nk_context` struct
* \param[in] x Must hold an integer describing the current mouse cursor x-position
* \param[in] y Must hold an integer describing the current mouse cursor y-position
*/
NK_API void nk_input_motion(struct nk_context*, int x, int y);
/**
* \brief Mirrors the state of a specific key to nuklear
*
* \details
* ```c
* void nk_input_key(struct nk_context*, enum nk_keys key, nk_bool down);
* ```
*
* \param[in] ctx Must point to a previously initialized `nk_context` struct
* \param[in] key Must be any value specified in enum `nk_keys` that needs to be mirrored
* \param[in] down Must be 0 for key is up and 1 for key is down
*/
NK_API void nk_input_key(struct nk_context*, enum nk_keys, nk_bool down);
/**
* \brief Mirrors the state of a specific mouse button to nuklear
*
* \details
* ```c
* void nk_input_button(struct nk_context *ctx, enum nk_buttons btn, int x, int y, nk_bool down);
* ```
*
* \param[in] ctx Must point to a previously initialized `nk_context` struct
* \param[in] btn Must be any value specified in enum `nk_buttons` that needs to be mirrored
* \param[in] x Must contain an integer describing mouse cursor x-position on click up/down
* \param[in] y Must contain an integer describing mouse cursor y-position on click up/down
* \param[in] down Must be 0 for key is up and 1 for key is down
*/
NK_API void nk_input_button(struct nk_context*, enum nk_buttons, int x, int y, nk_bool down);
/**
* \brief Copies the last mouse scroll value to nuklear.
*
* \details
* Is generally a scroll value. So does not have to come from mouse and could
* also originate from balls, tracks, linear guide rails, or other programs.
*
* ```c
* void nk_input_scroll(struct nk_context *ctx, struct nk_vec2 val);
* ```
*
* \param[in] ctx | Must point to a previously initialized `nk_context` struct
* \param[in] val | vector with both X- as well as Y-scroll value
*/
NK_API void nk_input_scroll(struct nk_context*, struct nk_vec2 val);
/**
* \brief Copies a single ASCII character into an internal text buffer
*
* \details
* This is basically a helper function to quickly push ASCII characters into
* nuklear.
*
* \note
* Stores up to NK_INPUT_MAX bytes between `nk_input_begin` and `nk_input_end`.
*
* ```c
* void nk_input_char(struct nk_context *ctx, char c);
* ```
*
* \param[in] ctx | Must point to a previously initialized `nk_context` struct
* \param[in] c | Must be a single ASCII character preferable one that can be printed
*/
NK_API void nk_input_char(struct nk_context*, char);
/**
* \brief Converts an encoded unicode rune into UTF-8 and copies the result into an
* internal text buffer.
*
* \note
* Stores up to NK_INPUT_MAX bytes between `nk_input_begin` and `nk_input_end`.
*
* ```c
* void nk_input_glyph(struct nk_context *ctx, const nk_glyph g);
* ```
*
* \param[in] ctx | Must point to a previously initialized `nk_context` struct
* \param[in] g | UTF-32 unicode codepoint
*/
NK_API void nk_input_glyph(struct nk_context*, const nk_glyph);
/**
* \brief Converts a unicode rune into UTF-8 and copies the result
* into an internal text buffer.
*
* \details
* \note
* Stores up to NK_INPUT_MAX bytes between `nk_input_begin` and `nk_input_end`.
*
* ```c
* void nk_input_unicode(struct nk_context*, nk_rune rune);
* ```
*
* \param[in] ctx | Must point to a previously initialized `nk_context` struct
* \param[in] rune | UTF-32 unicode codepoint
*/
NK_API void nk_input_unicode(struct nk_context*, nk_rune);
/**
* \brief End the input mirroring process by resetting mouse grabbing
* state to ensure the mouse cursor is not grabbed indefinitely.
*
* \details
* ```c
* void nk_input_end(struct nk_context *ctx);
* ```
*
* \param[in] ctx | Must point to a previously initialized `nk_context` struct
*/
NK_API void nk_input_end(struct nk_context*);
/** =============================================================================
*
* DRAWING
*
* =============================================================================*/
/**
* \page Drawing
* This library was designed to be render backend agnostic so it does
* not draw anything to screen directly. Instead all drawn shapes, widgets
* are made of, are buffered into memory and make up a command queue.
* Each frame therefore fills the command buffer with draw commands
* that then need to be executed by the user and his own render backend.
* After that the command buffer needs to be cleared and a new frame can be
* started. It is probably important to note that the command buffer is the main
* drawing API and the optional vertex buffer API only takes this format and
* converts it into a hardware accessible format.
*
* # Usage
* To draw all draw commands accumulated over a frame you need your own render
* backend able to draw a number of 2D primitives. This includes at least
* filled and stroked rectangles, circles, text, lines, triangles and scissors.
* As soon as this criterion is met you can iterate over each draw command
* and execute each draw command in a interpreter like fashion:
*
* ```c
* const struct nk_command *cmd = 0;
* nk_foreach(cmd, &ctx) {
* switch (cmd->type) {
* case NK_COMMAND_LINE:
* your_draw_line_function(...)
* break;
* case NK_COMMAND_RECT
* your_draw_rect_function(...)
* break;
* case //...:
* //[...]
* }
* }
* ```
*
* In program flow context draw commands need to be executed after input has been
* gathered and the complete UI with windows and their contained widgets have
* been executed and before calling `nk_clear` which frees all previously
* allocated draw commands.
*
* ```c
* struct nk_context ctx;
* nk_init_xxx(&ctx, ...);
* while (1) {
* Event evt;
* nk_input_begin(&ctx);
* while (GetEvent(&evt)) {
* if (evt.type == MOUSE_MOVE)
* nk_input_motion(&ctx, evt.motion.x, evt.motion.y);
* else if (evt.type == [...]) {
* [...]
* }
* }
* nk_input_end(&ctx);
* //
* // [...]
* //
* const struct nk_command *cmd = 0;
* nk_foreach(cmd, &ctx) {
* switch (cmd->type) {
* case NK_COMMAND_LINE:
* your_draw_line_function(...)
* break;
* case NK_COMMAND_RECT
* your_draw_rect_function(...)
* break;
* case ...:
* // [...]
* }
* nk_clear(&ctx);
* }
* nk_free(&ctx);
* ```
*
* You probably noticed that you have to draw all of the UI each frame which is
* quite wasteful. While the actual UI updating loop is quite fast rendering
* without actually needing it is not. So there are multiple things you could do.
*
* First is only update on input. This of course is only an option if your
* application only depends on the UI and does not require any outside calculations.
* If you actually only update on input make sure to update the UI two times each
* frame and call `nk_clear` directly after the first pass and only draw in
* the second pass. In addition it is recommended to also add additional timers
* to make sure the UI is not drawn more than a fixed number of frames per second.
*
* ```c
* struct nk_context ctx;
* nk_init_xxx(&ctx, ...);
* while (1) {
* // [...wait for input ]
* // [...do two UI passes ...]
* do_ui(...)
* nk_clear(&ctx);
* do_ui(...)
* //
* // draw
* const struct nk_command *cmd = 0;
* nk_foreach(cmd, &ctx) {
* switch (cmd->type) {
* case NK_COMMAND_LINE:
* your_draw_line_function(...)
* break;
* case NK_COMMAND_RECT
* your_draw_rect_function(...)
* break;
* case ...:
* //[...]
* }
* nk_clear(&ctx);
* }
* nk_free(&ctx);
* ```
*
* The second probably more applicable trick is to only draw if anything changed.
* It is not really useful for applications with continuous draw loop but
* quite useful for desktop applications. To actually get nuklear to only
* draw on changes you first have to define `NK_ZERO_COMMAND_MEMORY` and
* allocate a memory buffer that will store each unique drawing output.
* After each frame you compare the draw command memory inside the library
* with your allocated buffer by memcmp. If memcmp detects differences
* you have to copy the command buffer into the allocated buffer
* and then draw like usual (this example uses fixed memory but you could
* use dynamically allocated memory).
*
* ```c
* //[... other defines ...]
* #define NK_ZERO_COMMAND_MEMORY
* #include "nuklear.h"
* //
* // setup context
* struct nk_context ctx;
* void *last = calloc(1,64*1024);
* void *buf = calloc(1,64*1024);
* nk_init_fixed(&ctx, buf, 64*1024);
* //
* // loop
* while (1) {
* // [...input...]
* // [...ui...]
* void *cmds = nk_buffer_memory(&ctx.memory);
* if (memcmp(cmds, last, ctx.memory.allocated)) {
* memcpy(last,cmds,ctx.memory.allocated);
* const struct nk_command *cmd = 0;
* nk_foreach(cmd, &ctx) {
* switch (cmd->type) {
* case NK_COMMAND_LINE:
* your_draw_line_function(...)
* break;
* case NK_COMMAND_RECT
* your_draw_rect_function(...)
* break;
* case ...:
* // [...]
* }
* }
* }
* nk_clear(&ctx);
* }
* nk_free(&ctx);
* ```
*
* Finally while using draw commands makes sense for higher abstracted platforms like
* X11 and Win32 or drawing libraries it is often desirable to use graphics
* hardware directly. Therefore it is possible to just define
* `NK_INCLUDE_VERTEX_BUFFER_OUTPUT` which includes optional vertex output.
* To access the vertex output you first have to convert all draw commands into
* vertexes by calling `nk_convert` which takes in your preferred vertex format.
* After successfully converting all draw commands just iterate over and execute all
* vertex draw commands:
*
* ```c
* // fill configuration
* struct your_vertex
* {
* float pos[2]; // important to keep it to 2 floats
* float uv[2];
* unsigned char col[4];
* };
* struct nk_convert_config cfg = {};
* static const struct nk_draw_vertex_layout_element vertex_layout[] = {
* {NK_VERTEX_POSITION, NK_FORMAT_FLOAT, NK_OFFSETOF(struct your_vertex, pos)},
* {NK_VERTEX_TEXCOORD, NK_FORMAT_FLOAT, NK_OFFSETOF(struct your_vertex, uv)},
* {NK_VERTEX_COLOR, NK_FORMAT_R8G8B8A8, NK_OFFSETOF(struct your_vertex, col)},
* {NK_VERTEX_LAYOUT_END}
* };
* cfg.shape_AA = NK_ANTI_ALIASING_ON;
* cfg.line_AA = NK_ANTI_ALIASING_ON;
* cfg.vertex_layout = vertex_layout;
* cfg.vertex_size = sizeof(struct your_vertex);
* cfg.vertex_alignment = NK_ALIGNOF(struct your_vertex);
* cfg.circle_segment_count = 22;
* cfg.curve_segment_count = 22;
* cfg.arc_segment_count = 22;
* cfg.global_alpha = 1.0f;
* cfg.tex_null = dev->tex_null;
* //
* // setup buffers and convert
* struct nk_buffer cmds, verts, idx;
* nk_buffer_init_default(&cmds);
* nk_buffer_init_default(&verts);
* nk_buffer_init_default(&idx);
* nk_convert(&ctx, &cmds, &verts, &idx, &cfg);
* //
* // draw
* nk_draw_foreach(cmd, &ctx, &cmds) {
* if (!cmd->elem_count) continue;
* //[...]
* }
* nk_buffer_free(&cms);
* nk_buffer_free(&verts);
* nk_buffer_free(&idx);
* ```
*
* # Reference
* Function | Description
* --------------------|-------------------------------------------------------
* \ref nk__begin | Returns the first draw command in the context draw command list to be drawn
* \ref nk__next | Increments the draw command iterator to the next command inside the context draw command list
* \ref nk_foreach | Iterates over each draw command inside the context draw command list
* \ref nk_convert | Converts from the abstract draw commands list into a hardware accessible vertex format
* \ref nk_draw_begin | Returns the first vertex command in the context vertex draw list to be executed
* \ref nk__draw_next | Increments the vertex command iterator to the next command inside the context vertex command list
* \ref nk__draw_end | Returns the end of the vertex draw list
* \ref nk_draw_foreach | Iterates over each vertex draw command inside the vertex draw list
*/
enum nk_anti_aliasing {NK_ANTI_ALIASING_OFF, NK_ANTI_ALIASING_ON};
enum nk_convert_result {
NK_CONVERT_SUCCESS = 0,
NK_CONVERT_INVALID_PARAM = 1,
NK_CONVERT_COMMAND_BUFFER_FULL = NK_FLAG(1),
NK_CONVERT_VERTEX_BUFFER_FULL = NK_FLAG(2),
NK_CONVERT_ELEMENT_BUFFER_FULL = NK_FLAG(3)
};
struct nk_draw_null_texture {
nk_handle texture; /**!< texture handle to a texture with a white pixel */
struct nk_vec2 uv; /**!< coordinates to a white pixel in the texture */
};
struct nk_convert_config {
float global_alpha; /**!< global alpha value */
enum nk_anti_aliasing line_AA; /**!< line anti-aliasing flag can be turned off if you are tight on memory */
enum nk_anti_aliasing shape_AA; /**!< shape anti-aliasing flag can be turned off if you are tight on memory */
unsigned circle_segment_count; /**!< number of segments used for circles: default to 22 */
unsigned arc_segment_count; /**!< number of segments used for arcs: default to 22 */
unsigned curve_segment_count; /**!< number of segments used for curves: default to 22 */
struct nk_draw_null_texture tex_null; /**!< handle to texture with a white pixel for shape drawing */
const struct nk_draw_vertex_layout_element *vertex_layout; /**!< describes the vertex output format and packing */
nk_size vertex_size; /**!< sizeof one vertex for vertex packing */
nk_size vertex_alignment; /**!< vertex alignment: Can be obtained by NK_ALIGNOF */
};
/**
* \brief Returns a draw command list iterator to iterate all draw
* commands accumulated over one frame.
*
* \details
* ```c
* const struct nk_command* nk__begin(struct nk_context*);
* ```
*
* \param[in] ctx | must point to an previously initialized `nk_context` struct at the end of a frame