-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapg_console.h
196 lines (155 loc) · 9.48 KB
/
apg_console.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
/* =======================================================================================================================
APG_C - A Quake-style Console mini-library
Author: Anton Gerdelan - @capnramses
Language: C99
Status: Working. Not tested across compilers/platforms yet. Expect warnings.
Contact: <[email protected]>
Website: https://github.com/capnramses/apg - http://antongerdelan.net/
Licence: See bottom of this file.
Version History:
v0.3 - 2020/06/07 - Doubled length of tmp strings to avoid truncation warnings.
v0.2 - 2020/01/04 - Moved to apg libraries repository. Minor tweaks from testing in a game integration.
v0.1 - 2020/01/06 - Reduced interface. Moved from stored float cvars to addresses of existing vars. Data type is also specified for bool/int/uint/float support.
Instructions
============
* Just drop the 4 files into your project (console and pixel font source code).
* No external image or font assets are required. The font is hard-coded into the source code.
* This file is the console interface - #include "apg_console.h" in your application code.
* Your program handles keyboard capture and drawing.
* You then feed keyboard input to this console.
* You ask this console to render an RGBA image to memory.
* You then use that for drawing any way you like. You don't need a 3D graphics API.
The primary interface for user-entered text is:
apg_c_append_user_entered_text( str );
Where `str` can be a whole line or eg one character at a time.
Instructions end and are entered and parsed after a line break `\n` byte.
Autocompletion of user-entered text is supported. e.g. After you application detects the TAB key is pressed call:
apg_c_autocomplete();
Instructions may be of the following forms:
BUILT-IN-COMMAND [VARIABLE] [VALUE]
VARIABLE
FUNCTION [VALUE]
Built-in commands include:
"help" - list built-in commands.
"my_var 2.0" - set the value of a variable 'my_var'.
"my_var" - print the value of variable 'my_var'.
"clear" - invoke the 'clear' command.
"list_vars" - print registered variables and their values to drop-down console
"list_funcs" - print registered variables and their values to drop-down console
Variables may also be registered, or accessed programmatically:
apg_c_register_var( str, var_ptr, datatype )
apg_c_get_var()
C functions can be called from console by registering a command name and function to call.
Your callback functions must be in the form `bool my_function( float arg )`. If your function returns false the console prints an error message.
User functions always require 1 float argument but if it is called from the drop-down console without supplying an argument then the argument value is set to 0.
apg_c_register_func( str, function_ptr );
Scrolling output text may be interacted with programmatically:
apg_c_output_clear() - Clear the output text.
apg_c_print( str ) - Adds a line of text to the output such as a debug message.
apg_c_dump_to_stdout() - Writes the current console output text to stdout via printf().
apg_c_count_lines() - Counts the number of lines in the console output.
The console text may also be rendered out to an image for use in any graphical applications.
This is API-agnostic so must be converted to a texture to be used with 3D APIs.
apg_c_draw_to_image_mem() - Writes current console text on top of a pre-allocated image.
apg_c_image_redraw_required() - Check if anything has actually changed requiring a redraw. You should also redraw if eg the display area changes size.
======================================================================================================================= */
#pragma once
#ifdef __cplusplus
extern "C" {
#endif
#include <stdbool.h>
#include <stdint.h>
#define APG_C_UNUSED( x ) (void)( x ) // to suppress compiler warnings with unused/dummy arguments in callbacks
#define APG_C_STR_MAX 128 // maximum console string length. commands and variable names must be shorter than this.
#define APG_C_VARS_MAX 256 // maximum number of variables stored in console
#define APG_C_FUNCS_MAX 128 // maximum number of console commands
#define APG_C_OUTPUT_LINES_MAX 32 // maximum number of lines retained in output
/* =======================================================================================================================
user-entered text API. call these functions based on eg keyboard input.
======================================================================================================================= */
// RETURNS - true if a valid command was parsed out of str.
bool apg_c_append_user_entered_text( const char* str );
// removes the last char from the current user-entered string.
void apg_c_backspace( void );
// autocompletes the current user-entered text if it matches a command. call if i.e. the user presses 'TAB'
void apg_c_autocomplete( void );
// enters a command from recent history into the current user-entered text field. i.e. if user presses up cursor arrow.
// PARAMS - hist is the number of entries back from the most recent command entered. 0 is the previously-entered command.
void apg_c_reuse_hist( int hist );
void apg_c_clear_user_entered_text( void );
/* =======================================================================================================================
console output text API.
======================================================================================================================= */
void apg_c_output_clear( void );
// Appends str as an output line to the scrolling output
void apg_c_print( const char* str );
int apg_c_count_lines( void );
// printf everything in console to stdout stream
void apg_c_dump_to_stdout( void );
void apg_c_dump_to_buffer(char * buffer, int maxlen);
/* =======================================================================================================================
program <-> console variable and function linkage API
======================================================================================================================= */
typedef enum apg_c_var_datatype_t { APG_C_BOOL, APG_C_INT32, APG_C_UINT32, APG_C_FLOAT, APG_C_OTHER } apg_c_var_datatype_t;
typedef struct apg_c_var_t {
char str[APG_C_STR_MAX];
void* var_ptr;
apg_c_var_datatype_t datatype;
} apg_c_var_t;
// Registers and existing program variable with the console.
// WARNING Pointer is assumed to be valid for lifetime of console registration.
// PARAMS
// str - A name for the variable.
// var_ptr - Pointer to variable to register and use for this c_var.
// datatype - Data type of the variable pointed to by var_ptr. Determines how values can be set from the console.
// RETURNS
// false if failed ie not space left in array of var ptrs.
bool apg_c_register_var( const char* str, void* var_ptr, apg_c_var_datatype_t datatype );
// Fetches the address of a console variable with name `str`.
// RETURNS
// NULL if the variable does not exist.
// Address of the c_var entry with pointer and data type.
apg_c_var_t* apg_c_get_var( const char* str );
bool apg_c_register_func( const char* str, bool ( *fptr )( const char* arg_str ) );
#ifdef __cplusplus
}
#endif
/*
-------------------------------------------------------------------------------------
This software is available under two licences - you may use it under either licence.
-------------------------------------------------------------------------------------
FIRST LICENCE OPTION
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
Copyright 2019 Anton Gerdelan.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-------------------------------------------------------------------------------------
SECOND LICENCE OPTION
Public Domain (www.unlicense.org)
This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
software, either in source code form or as a compiled binary, for any purpose,
commercial or non-commercial, and by any means.
In jurisdictions that recognize copyright laws, the author or authors of this
software dedicate any and all copyright interest in the software to the public
domain. We make this dedication for the benefit of the public at large and to
the detriment of our heirs and successors. We intend this dedication to be an
overt act of relinquishment in perpetuity of all present and future rights to
this software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-------------------------------------------------------------------------------------
*/