Difference between revisions of "Changes from V2.x to V3.0"
(→The New GDISP API) |
|||
| (8 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | There are many major changes from uGFX V2.x to V3.0. While we have tried to maintain compatibility for most uGFX V2 applications there are some areas that will require re-writing. | + | There are many major changes from uGFX V2.x to V3.0. While we have tried to maintain compatibility for most uGFX V2 applications there are some areas that will require re-writing. Below is a short summary of the changes. Much more detail will be provided as the V3.0 release comes closer. |
| − | + | ||
== Compatibility == | == Compatibility == | ||
| − | The configuration option GFX_COMPAT_V2 is now defined that allows most V2.x code to compile unchanged. It is turned on by default. | + | The configuration option GFX_COMPAT_V2 is now defined that allows most V2.x application code to compile unchanged. It is turned on by default (at least until V3.1). The sections below will talk about where specific items of compatibility has changed. |
| − | + | A separate configuration option GFX_COMPAT_OLDCOLORS has also been created that controls the old uGFX color names. It also is turned on by default. The reason that this is separate from GFX_COMPAT_V2 is that for some operating systems it may be useful to turn off the old color definitions to prevent symbol conflicts even though you still want V2.x API compatibility. | |
| + | |||
| + | All the standard uGFX demo's have been updated to run in pure V3 mode (i.e. without GFX_COMPAT_V2 turned on). | ||
== Single-File-Make == | == Single-File-Make == | ||
| − | The single-file-make build mechanism now works with all uGFX features. | + | The single-file-make build mechanism now works with all uGFX features (including pixmaps). This will provide greater compatibility with systems such as Arduino and other IDE's. Even drivers can be included in the single-file-make so it is only necessary to include a single source file into your project to include all of uGFX. The original makefile build option is still supported and will work unchanged. |
| − | + | == Types, Constants and Configuration Options == | |
| + | Many types and constants have been renamed to prevent conflicts with other library, operating systems or other code. The old values will still work provided GFX_COMPAT_V2 is turned on. | ||
| − | + | General: | |
| − | + | * GFXON and GFXOFF replace TRUE/FALSE for configuration options | |
| + | * GTrue and GFalse replace TRUE/FALSE for the bool_t type. | ||
| − | + | GOS: | |
| + | * The configuration option GFX_OS_CALL_UGFXMAIN now defaults to GFXON if GFX_COMPAT_V2 is turned off. | ||
| + | * Individual GFX_USE_OS_xxx configuration options are replaced by GFX_OS=GFX_OS_xxx. GFX_COMPAT_V2 allows the old configuration options to still be used. | ||
| + | * The configuration option GFX_OS_EXTRA_INIT_FUNCTION has been renamed to GFX_OS_POST_INIT_FUNCTION | ||
| + | * The configuration option GFX_OS_EXTRA_DEINIT_FUNCTION has been renamed to GFX_OS_PRE_DEINIT_FUNCTION | ||
| + | * There is a new configuration option GFX_OS_POST_DEINIT_FUNCTION | ||
| + | |||
| + | GDISP: | ||
| + | * See below | ||
== The New GDISP API == | == The New GDISP API == | ||
| − | The GDISP API has been significantly changed. | + | The GDISP API has been significantly changed. There are many new types and new functionality is available. See the new GDISP API documentation for more details (when it is available). |
| − | More details to come | + | New Functionality: |
| + | * New alpha pixel color formats are now supported. GDISP color blending functions have been updated to match. | ||
| + | * More accurate color conversion is available between pixel formats | ||
| + | * Text drawing in other orientations is now available | ||
| + | * All displays can be rotated whether or not the driver supports it. Where the driver doesn't support it directly, the GDISP API performs the necessary rotations on the drawing operations although this may in some cases reduce drawing speed or require extra RAM buffers. Also supported are new partial orientations such as X axis mirroring. | ||
| + | * All drawing now occurs on a single "canvas" rather than on a specific display device. This means that display operations are much more clearly separated from drawing operations. See the multiple display section for more details. | ||
| + | * Flushing of drawing operations to the display can now be much more precisely controlled by the application. | ||
| + | * Significantly improved API. | ||
| + | |||
| + | Changes: | ||
| + | * The predefined colors GFX_BLACK, GFX_WHITE, GFX_RED etc replace the old color definitions Black, White, Red etc. | ||
| + | * Rounded boxes now require the new configuration option GDISP_NEED_ROUNDBOX. | ||
| + | * Thick lines now require the new configuration option GDISP_NEED_THICKLINES. | ||
| + | * Thick line arcs now require the new configuration option GDISP_NEED_THICKARC. | ||
| + | * Constants gOrientationXXX replace the V2 GDISP_ROTATE_xxx values | ||
| + | * Exact color macros EXACT_xxx_OF are now deprecated. They are still available with GFX_COMPAT_V2 but they work differently. See the new GFX_COLORCONVERT option | ||
| + | * Types gColor, gPixel & gPoint replace the old types color_t, pixel_t, point & point_t | ||
| + | * Types gOrientation, gPowerMode, gJustify replace the old types orientation_t, powermode_t, justify_t | ||
| + | * The configuration options GDISP_NEED_CLIP and GDISP_NEED_VALIDATION are now deprecated (and ignored). They are now effectively always on. | ||
| + | * There is a new configuration option GDISP_NEED_ORIENTATION option which was previously functionality that was bundled into GDISP_NEED_CONTROL. | ||
| + | * There is a new configuration option GDISP_NEED_BLENDING to enable/disable color blending/contrast functions. When GFX_COMPAT_V2 is on then this option is also on by default. | ||
| + | * There are new types to support the new API: gRect, gArea, gBacklight and gContrast | ||
| + | * There is a new configuration option GDISP_NEED_TEXT_ORIENTATION to support text orientation | ||
| + | * There is a new configuration option GDISP_COLORCONVERT to control color conversion strategy | ||
| + | |||
| + | More details to come... | ||
== Multiple Display Support == | == Multiple Display Support == | ||
| − | Multiple display support now works very differently. | + | Multiple display support now works very differently. Instead of having to specify the display device on every drawing operation, now every drawing operation occurs on a virtual "canvas". Displays now overlap a portion of the virtual canvas. This allows some interesting capabilities. |
| − | + | Case Study 1: Displays can be set to be side-by-side on the virtual canvas and drawing operations can span both display devices. This is similar to the way desktop operating systems handle multiple displays. | |
| + | |||
| + | Case Study 2: Two displays may overlap the same area of virtual canvas. This causes a single drawing operation to occur on both displays at the same time. A nice example of this would be a virtual network display that overlaps a physical LCD. Anything drawn on the physical LCD would also be drawn on the virtual network display. This can also be used with pixmaps (which are a type of virtual display). The pixmap could overlap the area of a widget label. Anything drawn on the widget label would automatically get drawn into the pixmap as well. | ||
== Adding Drivers To Your Build == | == Adding Drivers To Your Build == | ||
| − | All drivers are now included using configuration options rather than by linking. | + | All drivers are now included using configuration options rather than by linking them. This makes drivers much easier to include and build into projects. Unfortunately this means that all uGFX drivers have had to be rewritten and the interface has changed. This means that existing V2.x projects will need to be updated to include the configuration options for the drivers into the gfxconf.h file (or into your makefile C pre-processor symbols). It also means that most V2.x board files will need to be rewritten. |
| − | + | ||
| − | + | ||
== New Driver Format == | == New Driver Format == | ||
| − | All uGFX drivers now use a new internal API and have been rewritten. | + | All uGFX drivers now use a new internal API and have been rewritten. As they are now included as part of the uGFX compile, drivers are not allowed to have symbol conflicts with any other driver in the system. Whilst this is not a huge issue for the drivers themselves (as they are all rewritten for you already in the repository), this requirement also extends to the board files to interface them with actual hardware. This means that all board files will need to be rewritten. GDISP drivers are also structured differently and have new entry points in order to support the new GDISP API capabilities. |
| − | More details to come | + | While all board files will need to be rewritten, the new GBUS module will make that process much simpler. Most board interface files will now be much simpler. |
| + | |||
| + | More details to come... | ||
== The New GBUS Module == | == The New GBUS Module == | ||
| − | Many hardware interface details that needed to be written explicitly into every driver board file are now handled by a new GBUS module. | + | Many hardware interface details that needed to be written explicitly into every driver board file are now handled by a new GBUS module. A GBus driver provides a bus type interface to a hardware device. For example, a GBUS driver will exist for: |
| + | * STM32 SPI 8 bit bus | ||
| + | * STM32 FMSC 8 bit bus | ||
| + | * STM32 I2C bus | ||
| + | * AT91 9 bit SPI bus | ||
| + | * ChibiOS based 8 bit GPIO parallel bus. | ||
| + | * 16 bit variants of the above | ||
| + | etc. | ||
| − | More details to come | + | Generally the only thing required to use a GBUS is to add the required GBUS driver in your configuration options and then initialise it with the specific CPU pins you want it to use in your display driver board file. This is much simpler than the old way where every driver board file needed to write the full hardware interface code which was often CPU and operating system specific. |
| + | |||
| + | More details to come... | ||
== New Trig Functions == | == New Trig Functions == | ||
There are new triginomic functions that are significantly faster and more accurate than the old functions in GMISC. | There are new triginomic functions that are significantly faster and more accurate than the old functions in GMISC. | ||
| + | |||
| + | The major difference is that instead of specify angle from 0 to 360 degrees, it is now specified from 0.0 to 1.0 in 16:16 fixed point arithmetic. This gives much more accuracy than the previous 1 degree angle and is much faster for the CPU to perform the trig operations. | ||
More details to come | More details to come | ||
| + | |||
| + | == Changes V3.1 and beyond == | ||
| + | * GWIN event update | ||
| + | * GWIN window manager | ||
Latest revision as of 12:25, 10 March 2018
There are many major changes from uGFX V2.x to V3.0. While we have tried to maintain compatibility for most uGFX V2 applications there are some areas that will require re-writing. Below is a short summary of the changes. Much more detail will be provided as the V3.0 release comes closer.
Contents
Compatibility
The configuration option GFX_COMPAT_V2 is now defined that allows most V2.x application code to compile unchanged. It is turned on by default (at least until V3.1). The sections below will talk about where specific items of compatibility has changed.
A separate configuration option GFX_COMPAT_OLDCOLORS has also been created that controls the old uGFX color names. It also is turned on by default. The reason that this is separate from GFX_COMPAT_V2 is that for some operating systems it may be useful to turn off the old color definitions to prevent symbol conflicts even though you still want V2.x API compatibility.
All the standard uGFX demo's have been updated to run in pure V3 mode (i.e. without GFX_COMPAT_V2 turned on).
Single-File-Make
The single-file-make build mechanism now works with all uGFX features (including pixmaps). This will provide greater compatibility with systems such as Arduino and other IDE's. Even drivers can be included in the single-file-make so it is only necessary to include a single source file into your project to include all of uGFX. The original makefile build option is still supported and will work unchanged.
Types, Constants and Configuration Options
Many types and constants have been renamed to prevent conflicts with other library, operating systems or other code. The old values will still work provided GFX_COMPAT_V2 is turned on.
General:
- GFXON and GFXOFF replace TRUE/FALSE for configuration options
- GTrue and GFalse replace TRUE/FALSE for the bool_t type.
GOS:
- The configuration option GFX_OS_CALL_UGFXMAIN now defaults to GFXON if GFX_COMPAT_V2 is turned off.
- Individual GFX_USE_OS_xxx configuration options are replaced by GFX_OS=GFX_OS_xxx. GFX_COMPAT_V2 allows the old configuration options to still be used.
- The configuration option GFX_OS_EXTRA_INIT_FUNCTION has been renamed to GFX_OS_POST_INIT_FUNCTION
- The configuration option GFX_OS_EXTRA_DEINIT_FUNCTION has been renamed to GFX_OS_PRE_DEINIT_FUNCTION
- There is a new configuration option GFX_OS_POST_DEINIT_FUNCTION
GDISP:
- See below
The New GDISP API
The GDISP API has been significantly changed. There are many new types and new functionality is available. See the new GDISP API documentation for more details (when it is available).
New Functionality:
- New alpha pixel color formats are now supported. GDISP color blending functions have been updated to match.
- More accurate color conversion is available between pixel formats
- Text drawing in other orientations is now available
- All displays can be rotated whether or not the driver supports it. Where the driver doesn't support it directly, the GDISP API performs the necessary rotations on the drawing operations although this may in some cases reduce drawing speed or require extra RAM buffers. Also supported are new partial orientations such as X axis mirroring.
- All drawing now occurs on a single "canvas" rather than on a specific display device. This means that display operations are much more clearly separated from drawing operations. See the multiple display section for more details.
- Flushing of drawing operations to the display can now be much more precisely controlled by the application.
- Significantly improved API.
Changes:
- The predefined colors GFX_BLACK, GFX_WHITE, GFX_RED etc replace the old color definitions Black, White, Red etc.
- Rounded boxes now require the new configuration option GDISP_NEED_ROUNDBOX.
- Thick lines now require the new configuration option GDISP_NEED_THICKLINES.
- Thick line arcs now require the new configuration option GDISP_NEED_THICKARC.
- Constants gOrientationXXX replace the V2 GDISP_ROTATE_xxx values
- Exact color macros EXACT_xxx_OF are now deprecated. They are still available with GFX_COMPAT_V2 but they work differently. See the new GFX_COLORCONVERT option
- Types gColor, gPixel & gPoint replace the old types color_t, pixel_t, point & point_t
- Types gOrientation, gPowerMode, gJustify replace the old types orientation_t, powermode_t, justify_t
- The configuration options GDISP_NEED_CLIP and GDISP_NEED_VALIDATION are now deprecated (and ignored). They are now effectively always on.
- There is a new configuration option GDISP_NEED_ORIENTATION option which was previously functionality that was bundled into GDISP_NEED_CONTROL.
- There is a new configuration option GDISP_NEED_BLENDING to enable/disable color blending/contrast functions. When GFX_COMPAT_V2 is on then this option is also on by default.
- There are new types to support the new API: gRect, gArea, gBacklight and gContrast
- There is a new configuration option GDISP_NEED_TEXT_ORIENTATION to support text orientation
- There is a new configuration option GDISP_COLORCONVERT to control color conversion strategy
More details to come...
Multiple Display Support
Multiple display support now works very differently. Instead of having to specify the display device on every drawing operation, now every drawing operation occurs on a virtual "canvas". Displays now overlap a portion of the virtual canvas. This allows some interesting capabilities.
Case Study 1: Displays can be set to be side-by-side on the virtual canvas and drawing operations can span both display devices. This is similar to the way desktop operating systems handle multiple displays.
Case Study 2: Two displays may overlap the same area of virtual canvas. This causes a single drawing operation to occur on both displays at the same time. A nice example of this would be a virtual network display that overlaps a physical LCD. Anything drawn on the physical LCD would also be drawn on the virtual network display. This can also be used with pixmaps (which are a type of virtual display). The pixmap could overlap the area of a widget label. Anything drawn on the widget label would automatically get drawn into the pixmap as well.
Adding Drivers To Your Build
All drivers are now included using configuration options rather than by linking them. This makes drivers much easier to include and build into projects. Unfortunately this means that all uGFX drivers have had to be rewritten and the interface has changed. This means that existing V2.x projects will need to be updated to include the configuration options for the drivers into the gfxconf.h file (or into your makefile C pre-processor symbols). It also means that most V2.x board files will need to be rewritten.
New Driver Format
All uGFX drivers now use a new internal API and have been rewritten. As they are now included as part of the uGFX compile, drivers are not allowed to have symbol conflicts with any other driver in the system. Whilst this is not a huge issue for the drivers themselves (as they are all rewritten for you already in the repository), this requirement also extends to the board files to interface them with actual hardware. This means that all board files will need to be rewritten. GDISP drivers are also structured differently and have new entry points in order to support the new GDISP API capabilities.
While all board files will need to be rewritten, the new GBUS module will make that process much simpler. Most board interface files will now be much simpler.
More details to come...
The New GBUS Module
Many hardware interface details that needed to be written explicitly into every driver board file are now handled by a new GBUS module. A GBus driver provides a bus type interface to a hardware device. For example, a GBUS driver will exist for:
- STM32 SPI 8 bit bus
- STM32 FMSC 8 bit bus
- STM32 I2C bus
- AT91 9 bit SPI bus
- ChibiOS based 8 bit GPIO parallel bus.
- 16 bit variants of the above
etc.
Generally the only thing required to use a GBUS is to add the required GBUS driver in your configuration options and then initialise it with the specific CPU pins you want it to use in your display driver board file. This is much simpler than the old way where every driver board file needed to write the full hardware interface code which was often CPU and operating system specific.
More details to come...
New Trig Functions
There are new triginomic functions that are significantly faster and more accurate than the old functions in GMISC.
The major difference is that instead of specify angle from 0 to 360 degrees, it is now specified from 0.0 to 1.0 in 16:16 fixed point arithmetic. This gives much more accuracy than the previous 1 degree angle and is much faster for the CPU to perform the trig operations.
More details to come
Changes V3.1 and beyond
- GWIN event update
- GWIN window manager
