From 4054d9a190fba6aac9f87c10eebbe8247259abee Mon Sep 17 00:00:00 2001 From: Recep Aslantas Date: Sat, 8 Aug 2020 10:47:38 +0300 Subject: [PATCH] io: update documentation + README --- README.md | 1 + docs/source/opt.rst | 22 +++++++++++++++++----- include/cglm/io.h | 15 +++++++++++++++ 3 files changed, 33 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9cb73a9..aceb123 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ you have the latest version - **[new option]** by starting v0.4.5, you can disable alignment requirement, check options in docs. - **[major change]** by starting v0.5.0, vec3 functions use **glm_vec3_** namespace, it was **glm_vec_** until v0.5.0 - **[major change]** by starting v0.5.1, built-in alignment is removed from **vec3** and **mat3** types +- **[major change]** by starting v0.7.3, inline print functions are disabled in release/production mode to eliminate print costs (see options in documentation). Print output also improved. You can disable colors if you need (see documentation) #### Note for C++ developers: If you are not aware of the original GLM library yet, you may also want to look at: diff --git a/docs/source/opt.rst b/docs/source/opt.rst index 94b9a0c..0f26232 100644 --- a/docs/source/opt.rst +++ b/docs/source/opt.rst @@ -18,7 +18,7 @@ versor: 16 byte By starting **v0.4.5** cglm provides an option to disable alignment requirement. To enable this option define **CGLM_ALL_UNALIGNED** macro before all headers. You can define it in Xcode, Visual Studio (or other IDEs) or you can also prefer -to define it in build system. If you use pre-compiled verisons then you +to define it in build system. If you use pre-compiled versions then you have to compile cglm with **CGLM_ALL_UNALIGNED** macro. **VERY VERY IMPORTANT:** If you use cglm in multiple projects and @@ -55,11 +55,20 @@ Print Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. **CGLM_DEFINE_PRINTS** -2. **CGLM_NO_PRINTS_NOOP** +2. **CGLM_NO_PRINTS_NOOP** (use CGLM_DEFINE_PRINTS) -Inline prints are only enabled in DEBUG mode and if **CGLM_DEFINE_PRINTS** is defined. -If DEBUG is not enabled then print function bodies will be emptied to eliminate print function calls. -You can disable this feature too by defining **CGLM_NO_PRINTS_NOOP** macro top of cglm headers. +Inline prints are only enabled in **DEBUG** mode or if **CGLM_DEFINE_PRINTS** is defined. +**glmc_** versions will always print too. + +Because **cglm** tried to enable print functions in debug mode and disable them in +release/production mode to eliminate printing costs when we do not need them. + +**cglm** checks **DEBUG** or **_DEBUG** macros to test debug mode, if these are not working for you then you can use +**CGLM_DEFINE_PRINTS** to force enable, or create a PR to introduce new macro to test against debugging mode. + +If DEBUG mode is not enabled then print functions will be emptied to eliminate print function calls. +You can disable this feature too by defining **CGLM_DEFINE_PRINTS** macro top of cglm header +or in project/build settings... 3. **CGLM_PRINT_PRECISION** 5 @@ -71,3 +80,6 @@ if a number is greater than this value then %g will be used, since this is short 5. **CGLM_PRINT_COLOR** "\033[36m" 6. **CGLM_PRINT_COLOR_RESET** "\033[0m" + +You can disable colorful print output by defining **CGLM_PRINT_COLOR** and **CGLM_PRINT_COLOR_RESET** as empty macro. +Because some terminals may not support colors. diff --git a/include/cglm/io.h b/include/cglm/io.h index 33aa10b..d6f3cc4 100644 --- a/include/cglm/io.h +++ b/include/cglm/io.h @@ -15,6 +15,21 @@ CGLM_INLINE void glm_versor_print(versor vec, FILE *ostream); */ +/* + cglm tried to enable print functions in debug mode and disable them in + release/production mode to eliminate printing costs. + + if you need to force enable then define CGLM_DEFINE_PRINTS macro not DEBUG one + + Print functions are enabled if: + + - DEBUG or _DEBUG macro is defined (mostly defined automatically in debugging) + - CGLM_DEFINE_PRINTS macro is defined including release/production + which makes enabled printing always + - glmc_ calls for io are always prints + + */ + #ifndef cglm_io_h #define cglm_io_h #if defined(DEBUG) || defined(_DEBUG) \