diff options
Diffstat (limited to 'include/gdisp/options.h')
| -rw-r--r-- | include/gdisp/options.h | 201 |
1 files changed, 131 insertions, 70 deletions
diff --git a/include/gdisp/options.h b/include/gdisp/options.h index efabe417..650e81c5 100644 --- a/include/gdisp/options.h +++ b/include/gdisp/options.h @@ -21,11 +21,31 @@ * @{ */ /** - * @brief The priority of the GDISP thread. - * @details Defaults to NORMAL_PRIORITY + * @brief Should drawing operations be automatically flushed. + * @details Defaults to FALSE + * @note If set to FALSE and the controller requires flushing + * then the application must manually call @p gdispGFlush(). + * Setting this to TRUE causes GDISP to automatically flush + * after each drawing operation. Note this may be slow but enables + * an application to avoid having to manually call the flush routine. + * @note If TRUE and GDISP_NEED_TIMERFLUSH is also TRUE, this takes precedence. + * @note Most controllers don't need flushing which is why this is set to + * FALSE by default. + */ + #ifndef GDISP_NEED_AUTOFLUSH + #define GDISP_NEED_AUTOFLUSH FALSE + #endif + /** + * @brief Should drawing operations be automatically flushed on a timer. + * @details Defaults to FALSE, Can be set to FALSE or a timer period in milliseconds. + * @note The period should not be set too short or it will consume all your CPU. A + * value between 250 and 500 milliseconds would probably be suitable. + * @note If TRUE and GDISP_NEED_AUTOFLUSH is also TRUE, this is ineffective. + * @note Most controllers don't need flushing which is why this is set to + * FALSE by default. */ - #ifndef GDISP_THREAD_PRIORITY - #define GDISP_THREAD_PRIORITY NORMAL_PRIORITY + #ifndef GDISP_NEED_TIMERFLUSH + #define GDISP_NEED_TIMERFLUSH FALSE #endif /** * @brief Should all operations be clipped to the screen and colors validated. @@ -33,49 +53,67 @@ * @note If this is FALSE, any operations that extend beyond the * edge of the screen will have undefined results. Any * out-of-range colors will produce undefined results. - * @note If defined then all low level and high level GDISP driver routines - * must check the validity of inputs and do something sensible - * if they are out of range. It doesn't have to be efficient, - * just valid. + * @note This should always be left as the default (TRUE) unless you + * are a maniac for speed and you have thoroughly tested your code + * and it never overwrites the edges of the screen. + * @note Setting GDISP_NEED_CLIP to TRUE internally uses the same mechanism + * as this validation. There is no advantage in setting this FALSE if + * GDISP_NEED_CLIP is TRUE. */ #ifndef GDISP_NEED_VALIDATION - #define GDISP_NEED_VALIDATION TRUE + #define GDISP_NEED_VALIDATION TRUE #endif /** * @brief Are clipping functions needed. * @details Defaults to TRUE */ #ifndef GDISP_NEED_CLIP - #define GDISP_NEED_CLIP TRUE + #define GDISP_NEED_CLIP TRUE + #endif + /** + * @brief Streaming functions are needed + * @details Defaults to FALSE. + */ + #ifndef GDISP_NEED_STREAMING + #define GDISP_NEED_STREAMING FALSE #endif /** * @brief Are text functions needed. * @details Defaults to FALSE + * @note You must also define at least one font. */ #ifndef GDISP_NEED_TEXT - #define GDISP_NEED_TEXT FALSE + #define GDISP_NEED_TEXT FALSE #endif /** * @brief Are circle functions needed. - * @details Defaults to TRUE + * @details Defaults to FALSE + * @note Uses integer algorithms only. It does not use any trig or floating point. */ #ifndef GDISP_NEED_CIRCLE - #define GDISP_NEED_CIRCLE TRUE + #define GDISP_NEED_CIRCLE FALSE #endif /** * @brief Are ellipse functions needed. * @details Defaults to FALSE + * @note Uses integer algorithms only. It does not use any trig or floating point. */ #ifndef GDISP_NEED_ELLIPSE - #define GDISP_NEED_ELLIPSE FALSE + #define GDISP_NEED_ELLIPSE FALSE #endif /** * @brief Are arc functions needed. * @details Defaults to FALSE - * @note Requires the maths library to be included in the link. ie -lm + * @note This can be compiled using fully integer mathematics by + * defining GFX_USE_GMISC and GMISC_NEED_FIXEDTRIG as TRUE. + * @note This can be compiled to use floating point but no trig functions + * by defining GFX_USE_GMISC and GMISC_NEED_FASTTRIG as TRUE. + * @note If neither of the above are defined it requires the maths library + * to be included in the link to provide floating point and trig support. + * ie include -lm in your compiler flags. */ #ifndef GDISP_NEED_ARC - #define GDISP_NEED_ARC FALSE + #define GDISP_NEED_ARC FALSE #endif /** * @brief Are convex polygon functions needed. @@ -95,7 +133,7 @@ * option will cause a compile error. */ #ifndef GDISP_NEED_SCROLL - #define GDISP_NEED_SCROLL FALSE + #define GDISP_NEED_SCROLL FALSE #endif /** * @brief Is the capability to read pixels back needed. @@ -105,7 +143,7 @@ * option will cause a compile error. */ #ifndef GDISP_NEED_PIXELREAD - #define GDISP_NEED_PIXELREAD FALSE + #define GDISP_NEED_PIXELREAD FALSE #endif /** * @brief Control some aspect of the hardware operation. @@ -114,7 +152,7 @@ * screen rotation, backlight levels, contrast etc */ #ifndef GDISP_NEED_CONTROL - #define GDISP_NEED_CONTROL FALSE + #define GDISP_NEED_CONTROL FALSE #endif /** * @brief Query some aspect of the hardware operation. @@ -122,21 +160,58 @@ * @note This allows query of hardware specific features */ #ifndef GDISP_NEED_QUERY - #define GDISP_NEED_QUERY FALSE + #define GDISP_NEED_QUERY FALSE #endif /** * @brief Is the image interface required. * @details Defaults to FALSE */ #ifndef GDISP_NEED_IMAGE - #define GDISP_NEED_IMAGE FALSE + #define GDISP_NEED_IMAGE FALSE #endif +/** + * @} + * + * @name GDISP Multiple Display Support + * @{ + */ /** - * @brief Is the messaging api interface required. - * @details Defaults to FALSE + * @brief The total number of displays. + * @note This can be on just one type of controller or spread across several different controllers */ - #ifndef GDISP_NEED_MSGAPI - #define GDISP_NEED_MSGAPI FALSE + #ifndef GDISP_TOTAL_DISPLAYS + #define GDISP_TOTAL_DISPLAYS 1 + #endif + /** + * @brief The total number of controllers. + * @note If this is greater than one, all the hardware acceleration options below + * and the pixel format must be manually specified in your gfxconf.h along with + * @p GDISP_CONTROLLER_LIST. See the gdisp_lld_config.h in each driver to get a list + * of hardware capabilities for each driver in order to work out the common set across + * all the controllers you want to use. + */ + #ifndef GDISP_TOTAL_CONTROLLERS + #define GDISP_TOTAL_CONTROLLERS 1 + #endif + + #if defined(__DOXYGEN__) + /** + * @brief The list of controllers. + * @note This is required if @p GDISP_TOTAL_CONTROLLERS is greater than one. + * @note The number of entries must match @p GDISP_TOTAL_CONTROLLERS. + * @note See the gdisp_lld.c in each driver (near the top) to get the name of the VMT for a driver. + * @note Replace this example with your own definition in your gfxconf.h file. + */ + #define GDISP_CONTROLLER_LIST GDISPVMT_Win32, GDISPVMT_SSD1963 + /** + * @brief The number of displays for each controller. + * @note This is required if @p GDISP_TOTAL_CONTROLLERS is greater than one. + * @note The number of entries must match @p GDISP_TOTAL_CONTROLLERS. + * @note The sum of all the display counts must equal @p GDISP_TOTAL_DISPLAYS (3 for this example) + * or bad things will happen. + * @note Replace this example with your own definition in your gfxconf.h file. + */ + #define GDISP_CONTROLLER_DISPLAYS 2, 1 #endif /** * @} @@ -150,42 +225,42 @@ * @details Defaults to FALSE */ #ifndef GDISP_NEED_IMAGE_NATIVE - #define GDISP_NEED_IMAGE_NATIVE FALSE + #define GDISP_NEED_IMAGE_NATIVE FALSE #endif /** * @brief Is GIF image decoding required. * @details Defaults to FALSE */ #ifndef GDISP_NEED_IMAGE_GIF - #define GDISP_NEED_IMAGE_GIF FALSE + #define GDISP_NEED_IMAGE_GIF FALSE #endif /** * @brief Is BMP image decoding required. * @details Defaults to FALSE */ #ifndef GDISP_NEED_IMAGE_BMP - #define GDISP_NEED_IMAGE_BMP FALSE + #define GDISP_NEED_IMAGE_BMP FALSE #endif /** * @brief Is JPG image decoding required. * @details Defaults to FALSE */ #ifndef GDISP_NEED_IMAGE_JPG - #define GDISP_NEED_IMAGE_JPG FALSE + #define GDISP_NEED_IMAGE_JPG FALSE #endif /** * @brief Is PNG image decoding required. * @details Defaults to FALSE */ #ifndef GDISP_NEED_IMAGE_PNG - #define GDISP_NEED_IMAGE_PNG FALSE + #define GDISP_NEED_IMAGE_PNG FALSE #endif /** * @brief Is memory accounting required during image decoding. * @details Defaults to FALSE */ #ifndef GDISP_NEED_IMAGE_ACCOUNTING - #define GDISP_NEED_IMAGE_ACCOUNTING FALSE + #define GDISP_NEED_IMAGE_ACCOUNTING FALSE #endif /** * @} @@ -198,7 +273,7 @@ * @details Defaults to FALSE */ #ifndef GDISP_NEED_UTF8 - #define GDISP_NEED_UTF8 FALSE + #define GDISP_NEED_UTF8 FALSE #endif /** @@ -206,7 +281,7 @@ * @details Defaults to FALSE */ #ifndef GDISP_NEED_TEXT_KERNING - #define GDISP_NEED_TEXT_KERNING FALSE + #define GDISP_NEED_TEXT_KERNING FALSE #endif /** @@ -214,7 +289,7 @@ * @details Defaults to FALSE */ #ifndef GDISP_NEED_ANTIALIAS - #define GDISP_NEED_ANTIALIAS FALSE + #define GDISP_NEED_ANTIALIAS FALSE #endif /** @@ -226,27 +301,10 @@ /** * @brief Do the drawing functions need to be thread-safe. * @details Defaults to FALSE - * @note Both GDISP_NEED_MULTITHREAD and GDISP_NEED_ASYNC make - * the gdisp API thread-safe. - * @note This is more efficient than GDISP_NEED_ASYNC as it only - * requires a context switch if something else is already - * drawing. */ #ifndef GDISP_NEED_MULTITHREAD #define GDISP_NEED_MULTITHREAD FALSE #endif - /** - * @brief Use asynchronous calls (multi-thread safe). - * @details Defaults to FALSE - * @note Both GDISP_NEED_MULTITHREAD and GDISP_NEED_ASYNC make - * the gdisp API thread-safe. - * @note Turning this on adds two context switches per transaction - * so it can significantly slow graphics drawing but it allows - * drawing operations to continue in the background. - */ - #ifndef GDISP_NEED_ASYNC - #define GDISP_NEED_ASYNC FALSE - #endif /** * @} * @@ -264,6 +322,23 @@ * @name GDISP Optional Sizing Parameters * @{ */ + /** + * @brief The size of pixel buffer (in pixels) used for optimization. + * @details Set to zero to guarantee disabling of the buffer. + * @note Depending on the driver and what operations the application + * needs, this buffer may never be allocated. + * @note Setting the size to zero may cause some operations to not + * compile eg. Scrolling if there is no hardware scroll support. + * @note Increasing the size will speedup certain operations + * at the expense of RAM. + * @note Currently only used to support scrolling on hardware without + * scrolling support, and to increase the speed of streaming + * operations on non-streaming hardware where there is a + * hardware supported bit-blit. + */ + #ifndef GDISP_LINEBUF_SIZE + #define GDISP_LINEBUF_SIZE 128 + #endif /** * @} * @@ -271,14 +346,10 @@ * @{ */ /** - * @brief Use a custom board definition even if a board definition exists. - * @details Defaults to FALSE - * @details If TRUE, add gdisp_lld_board.h to your project directory and customise it. - * @note Not all GDISP low level drivers currently use board definition files. + * @brief Define the default orientation for all displays in the system. + * @note GDISP_NEED_CONTROL must also be set (and the hardware must support it) */ - #ifndef GDISP_USE_CUSTOM_BOARD - #define GDISP_USE_CUSTOM_BOARD FALSE - #endif + // #define GDISP_DEFAULT_ORIENTATION GDISP_ROTATE_LANDSCAPE /** * @brief Set the screen height and width. * @note Ignored by some low level GDISP drivers, optional for others. @@ -289,24 +360,14 @@ /* #define GDISP_SCREEN_WIDTH nnnn */ /* #define GDISP_SCREEN_HEIGHT nnnn */ /** - * @brief Define which threading model to use. - * @details Optional for the X11 driver. - * @note Defaults to TRUE. Setting to FALSE causes POSIX threads to be used - */ - /* #define GDISP_THREAD_CHIBIOS FALSE */ - /** * @brief Define which bus interface to use. * @details Only required by the SSD1963 driver. * @note This will be replaced eventually by board definition files */ - /* #define GDISP_USE_FSMC */ - /* #define GDISP_USE_GPIO */ + // #define GDISP_USE_FSMC + // #define GDISP_USE_GPIO /** @} */ -#if GFX_USE_GDISP - #include "gdisp_lld_config.h" -#endif - #endif /* _GDISP_OPTIONS_H */ /** @} */ |