Jump to content

Upcoming uGFX versions v2.8 and v3.0

Recommended Posts

For a while now we have been working on a new version of uGFX that includes many fundamental changes including changes that will affect compatibility with the uGFX API. This new work we have loosely labelled uGFX V3/4.

As the changes are so significant we have decided to start to integrate some of these changes back into the current version of uGFX in a manner that disrupts as few existing applications as possible.

This note is therefore to say that uGFX V2.8 will be the last official release of uGFX v2.x and it will be released at the same time uGFX v3.0 is released.

The next major release uGFX v3.0 will retain the existing uGFX user API but the driver interface will be changing.

The consequence of this are:

  • If you are using a custom board file (not one of the standard ones we provide as part of the repository), you will need to rewrite your board file for the new driver architecture to use uGFX v3.x.
  • If you have a custom driver for your display or touch device it will need to be rewritten to conform to the new driver API to use uGFX v3.x.
  • Some new API's may appear in uGFX v3.x that seem to replicate existing uGFX functionality. These new API's will be part of the future API for uGFX and the old calls will eventually be deprecated (although not in uGFX v3.x). Note that during uGFX v3.x these new API's may change as the technology develops. It is therefore recommended that these new API's be considered for usage in new applications particularly where long term usage with future versions of uGFX is important. Where stability with a particular version of uGFX is important it is recommended to use the old APIs. 

To aid in the migration process for custom drivers and board files for common hardware, if you contribute that to uGFX before uGFX V3.0 is officially released we will attempt to port the driver/board file to the new format for you. We may ask you to test that for us as the official release of uGFX v3.0 comes closer. Once uGFX V3.0 is released we will provide no more support or porting for the uGFX V2.x drivers and board files except via paid support.

A new uGFX3 branch has been created in the source repository. Prior to the uGFX v3.0 release and starting immediately the uGFX3  will be the main development branch. Only bug fixes and contributed v2.x drivers/board files will be ported back to the master branch to form the basis of uGFX v2.8. This will leave the master branch as the most stable version of uGFX. The new uGFX3 branch may be unstable and may not always compile prior to the uGFX v3.0 release.

Once uGFX v3.0 and uGFX v2.8 is released the uGFX3 branch will be merged into the master branch. uGFX v2.x will then enter a period of where only critical bug fixes will be posted and only for a short period much the same way that other version releases are made in uGFX.

There is currently no defined timeline for when uGFX v2.8 and uGFX v3.0 is released - just that the process has started.

We will post additional information in this thread about the changes as we progress.

Link to post
Share on other sites

The first of the new capabilities are now in the uGFX3 branch. Unfortunately it probably won't compile just yet.

The new features:

  • There is a new configuration option GFX_COMPAT_V2. This is turned on by default. It will enable compatibility with the uGFX V2.x API.
  • Configuration options will now be set with GFXON and GFXOFF rather than TRUE/FALSE. TRUE/FALSE are maintained for compatibility when GFX_COMPAT_V2 is turned on.
  • The bool_t data type has new value macros GTrue and GFalse. This, and the item above mean that TRUE and FALSE are no longer required by uGFX. They will only be defined if the operating system uGFX runs on defines them (or GFX_COMPAT_V2 is turned on). This prevents some type conflicts with strange side effects for some operating systems.
  • Similarly the color definitions Red, Green, Blue, Black, White etc are being replaced by GFXRED, GFXGREEN, GFXBLUE, GFXWHITE etc. This prevents name conflicts with some platforms such as Win32 and the STM32 HAL where they are defined differently. The configuration option GFX_COMPAT_OLDCOLORS allows the old color definitions to still be used and is turned on by default. GFX_COMPAT_V2 is also required.
  • Work has started on allowing drivers to be included purely by setting a configuration option rather than having to add it to the makefile. eg GDISP_DRIVER_WIN32 or GDISP_DRIVER_ILI9341. This is going to require a whole new driver API and lots of driver conversion. At the same time it is intended to clean up the drivers and board files to prevent symbol conflicts that currently stop drivers being part of the single file make system. Once complete this will also fix the compatibility issues between the single file make system and certain features such as pixmaps.

That's all for now. We will let you know more as time goes by.


Link to post
Share on other sites
  • 3 months later...

uGFX V3.0 is now (intermittently) compilable. Adding GBUS (see below) may have broken it today but generally the V3.0 branch will now compile subject to certain restrictions. Those restrictions currently are:

  • Win32 platform only (GFX_USE_OS_WIN32 = GFXON) 
  • Only with functionality in the GDISP basics demo

Some more new features for uGFX V3.0:

  • gColor, gPixel & gPoint replace the old types color_t, pixel_t, point & point_t. Again the old types are still available if you have set GFX_COMPAT_V2
  • A new config option GDISP_NEED_ORIENTATION has been created. Orientation support (being able to rotate the whole display) can add a fair bit of code and tends to be either used or not depending on the application. Orientation support used to be part of the GDISP_NEED_CONTROL option.
  • We are trying to implement display orientation support that is provided by the GDISP layer itself even when the display controller doesn't support it. While it may still work for a display controller with no orientation support, it may operate a little less efficiently. Final details on this feature will be released once more of the new GDISP driver architecture is finalised.
  • All GDISP drivers (and hopefully all other drivers by the time we are complete) will be able to be included by defining an option in your gfxconf.h file. This then makes all such drivers compatible with single-file-make scenarios. There will be no need to separately compile or link the driver into uGFX.
  • A new module GBUS has been added. Many drivers require access to a hardware bus of some sort, be it parallel, SPI or I2C. Previously each bus call was enumerated in each driver board file. What this meant is that there was a lot of code replication between boards and it was easy to get the hardware interface wrong. With the new GBUS module you will be able to use any of the predefined bus types and just hook it to your driver in the board init call. This will significantly simplify using a custom hardware interface or pin-out with a standard peripheral such as the LCD. A single LCD driver could then theoretically work on a SPI, I2C, 8bit parallel or 16bit parallel bus simply by changing the bus that is connected to the driver (subject to the controller supporting that). It also means that complexities such as pin initialisation, busy waiting vs yielding, DMA or non-DMA can be transparently handled for the user ensuring the most efficient mechanism of talking to the bus.
    While no drivers for GBUS have yet been written, some of the drivers might be things like STM32_SPI_WITH_DC, STM32_I2C, STM32_Parellel_8bit, STM32_Parellel_16bit, STM32_Parellel_16bit_over_8bit_MSB_first, AT91_SPI, MSP430_I2C, ChibiOS_SPI, ChibiOS_Parellel_8bit etc.
  • Although not finalised yet, we are looking to add new integer trigonomic functions (eg sin, cos, atan2) that rely on integer boundaries and table lookup to provide very fast trigonomic operations with high accuracy with very small table sizes. With a 256 byte table (held in flash/ROM) the angular accuracy should be around +/- 0.35o (0.006 radians). Unfortunately the API will be different to the existing uGFX V2.x trigonomic API as the old API simply couldn't represent any angle less than 1o. GFX_COMPAT_V2 will allow the old API to still be used albeit with its existing limited resolution.

Call for assistance:

uGFX V3.0 is going to be a big job to release. At this stage we are hoping for around June/July but there is no guarantees that we will be even close to that date. We would therefore be very interested in any one prepared to help with testing V3.0, or with converting drivers to uGFX V3.0 as we get closer to the release date. Please send me a private message if you are prepared to help and in what capacity and/or how much time you can commit. Depending on the response we may be prepared to offer (minor) incentives eg perhaps a commercial license, an embedded board, early access to the new version of uGFX Studio or something else that interests you. No promises here though - we just want to make sure you know we appreciate your efforts.

That's all for now. We will let you know when something else interesting happens.


Link to post
Share on other sites
  • 1 month later...


First I have to say a big thank you for the good job you are doing. compared to emWin you guys just didn't get the fame.


I am planning to start working on a project and I've been waiting a while for V3.0 to be released but it seems there's still no estimation.

I have to add my own display driver and I thought I should just wait so I can write it in the new format.

So now that you're getting closer to the release, is it possible to estimate a release date?

Link to post
Share on other sites

Not yet unfortunately. The reason is that we have just been so busy and we are very resource constrained. We have two VERY large projects that are currently consuming us. We had actually hoped to have it out by now.

What is coming very soon is a V2.9 which contains some of the type changes that were part of V3. We are taking this step for two reasons; one to keep uGFX moving forward, and secondly to reduce the workload with keeping V2 alive while V3 is being developed (the internal source changes are quite significant).

With regard to your planned driver, if you develop it for V2 and contribute it to the repository we will port it to V3 as part of the V3 effort. We may need your help testing it but we will cover the porting work.

Link to post
Share on other sites
  • 1 month later...

We have just pushed another major step towards V3.

This version replaces types such as bool_t, int8_t etc with our own internal typed gBool, gI8, gU8 etc. As always the old types are still defined and compatible because GFX_COMPAT_V2 is set to GFXON by default.

Internally we are now using a mix of the old and new types however that will be updated over the next few commits to just use the new types.

In the mean time we ask that people please test their compilation with the new source to make sure we haven't broken support for your operating system or compiler. If we have please let us know via the normal support forum/topics.

Link to post
Share on other sites
  • 3 weeks later...

Some more changes moving toward V3.

CHANGE: Added type gDelay to replace V2.x delaytime_t and values gDelayNone/gDelayForever to replace TIME_IMMEDIATE/TIME_INFINITE

CHANGE: Added type gTicks to replace V2.x systemticks_t

CHANGE: Added type gThread to replace V2.x gfxThreadHandle

CHANGE: Added type gThreadreturn to replace V2.x threadreturn_t

CHANGE: Added type gThreadpriority to replace V2.x threadpriority_t and values gThreadpriorityLow/Normal/High to replace LOW_/NORMAL_/HIGH_PRIORITY

CHANGE: Added type gPoint to replace V2.x point and point_t

CHANGE: Added type gCoord to replace V2.x coord_t

CHANGE: Added type gPixel to replace V2.x pixel_t

CHANGE: Added type gColor to replace V2.x color_t

CHANGE: Added type gColorformat to replace V2.x colorformat

CHANGE: Added type gFont to replace V2.x font_t

CHANGE: Added type gPowermode to replace V2.x powermode_t, and values gPowerXXX replace powerXXX

CHANGE: Added type gJustify to replace V2.x justify_t, and values gJustifyXXX replace justifyXXX

CHANGE: Added type gFontmetric to replace V2.x fontmetric_t, and values gFontXXX replace fontXXX

CHANGE: Added type gOrientation to replace V2.x orientation_t, and values gOrientationX replace GDISP_ROTATE_X



As always the old types are still defined and compatible because GFX_COMPAT_V2 is set to GFXON by default.

Link to post
Share on other sites
  • 3 months later...
  • 1 year later...

Hi there,


I'm just wondering about progress towards v3. The uGFX site says "actively developed" but there hasn't been any substantial commits for 8 months (besides a comment fix a week ago).

We're hoping to use uGFX in a commercial product if possible, but we're scared to use a library that will not be actively maintained. Any update would be appreciated!




Link to post
Share on other sites

The µGFX library is actively maintained.
There is currently no release date for µGFX v3 as we want to put our best efforts into it. The development repository of v3 is not public hence there's very little publicly visible efforts.

µGFX v2.9 is known to be stable. While we do not currently add new features to it we are applying patches & hotfixes as they appear.

We can only recommend using the µGFX library in your commercial product ?
If it helps: There's an equally named company behind the µGFX library - This is not just a floating piece of software. Also professional support is being handled through this company.

Link to post
Share on other sites
  • 7 months later...
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Create New...