Commit f9fd2955 authored by Vincent Wei's avatar Vincent Wei

Supplementary Documents

parent 1aa2c783
This diff is collapsed.
......@@ -4,10 +4,30 @@ We maintains the documents for MiniGUI Core and MiniGUI Components in this proje
## Contents
- [MiniGUI Overview](MiniGUI-Overview.md)
- [MiniGUI User Manual](user-manual/README.md)
- [MiniGUI Programming Guide](programming-guide/README.md)
- [MiniGUI Porting Guide](porting-guide/README.md)
- [MiniGUI API Reference Manuals](api-reference/README.md)
* [MiniGUI 4.0 API Reference (MiniGUI-Processes mode)](http://www.minigui.com/doc-api-ref-minigui-procs-4.0.0/html/index.html) - The API reference for MiniGUI V4.0 multi-process runmode.
* [MiniGUI 4.0 API Reference (MiniGUI-Threads mode)](http://www.minigui.com/doc-api-ref-minigui-ths-4.0.0/html/index.html) - The API reference for MiniGUI V4.0 multi-thread runmode.
* [MiniGUI 4.0 API Reference (MiniGUI-Standalone mode)](http://www.minigui.com/doc-api-ref-minigui-sa-4.0.0/html/index.html) - The API reference for MiniGUI V4.0 standalone runmode.
* [MiniGUI 3.2 API Reference (MiniGUI-Processes mode)](http://www.minigui.com/api_ref/minigui-3.2.0/procs/index.html) - The API reference for MiniGUI V3.2 multi-process runmode.
* [MiniGUI 3.2 API Reference (MiniGUI-Threads mode)](http://www.minigui.com/api_ref/minigui-3.2.0/ths/index.html) - The API reference for MiniGUI V3.2 multi-thread runmode.
* [MiniGUI 3.2 API Reference (MiniGUI-Standalone mode)](http://www.minigui.com/api_ref/minigui-3.2.0/sa/index.html) - The API reference for MiniGUI V3.2 standalone runmode.
- API Reference for MiniGUI Components
* [mGUtils 1.2 API Reference](http://www.minigui.com/doc-api-ref-mgutils-1.2.2/html/index.html) - The API reference for mGUtils V1.2.
* [mGPlus 1.4 API Reference](http://www.minigui.com/doc-api-ref-mgplus-1.4.0/html/index.html) - The API reference for mGUtils V1.4.
* [mGEff 1.2 API Reference](http://www.minigui.com/doc-api-ref-mgeff-1.2.2/html/index.html) - The API reference for mGEff V1.2.
* [mGNCS 1.2 API Reference](http://www.minigui.com/doc-api-ref-mgncs-1.2.4/html/index.html) - The API reference for mGNCS V1.2.
* [mGNCS4Touch 1.2 API Reference](http://www.minigui.com/doc-api-ref-mgncs4touch-1.2.2/html/index.html) - The API reference for mGNCS4Touch V1.2.
- Links to Release Notes
* [MiniGUI Core](https://github.com/VincentWei/minigui/blob/master/RELEASE-NOTES.md)
* [mGUtils](https://github.com/VincentWei/mgutils/blob/master/RELEASE-NOTES.md)
* [mGPlus](https://github.com/VincentWei/mgplus/blob/master/RELEASE-NOTES.md)
* [mGEff](https://github.com/VincentWei/mgeff/blob/master/RELEASE-NOTES.md)
* [mGNCS](https://github.com/VincentWei/mgncs/blob/master/RELEASE-NOTES.md)
* [mGNCS4Touch](https://github.com/VincentWei/mgncs4touch/blob/master/RELEASE-NOTES.md)
## Current Status
......
# MiniGUI Supplementary Documents
Good software requires good documentation, especially system software like
MiniGUI. However, maintaining documentation for a complex software system
is a lot more difficult than maintaining source code.
It sounds like it is always better if there are documents than no documents,
but if the documents are outdated or contain errors, the damage will be
even greater. So there is a saying: "Source code is the best document."
Therefore, we don't particularly want to spend a lot of time writing and
maintaining documentation.
On the other hand, facing some new features, the developers, especially
the beginners, still need some basic documents or guides to quickly
understand how they work and how to use them.
In the past many years, we have accumulated a large number of MiniGUI
documents, including user manuals, programming guides, and so on.
With the releases of new MiniGUI versions (like MiniGUI 3.2 and
MiniGUI 4.0), it doesn't make much sense to update or rewrite these
documents throughout just for some new features.
Therefore, we plan to write some new documents or guides on this
GitHub Wiki system, by supplementing the existing documents instead
of updating the existing ones. These documents will not be very detailed,
but will point out the main points and related sample programs to
help you quickly grasp the relevant features.
We call these documents "MiniGUI Supplementary Documents".
## Features for Version 4.0 or later
* [Release Notes for MiniGUI 4.0](Release-Notes-for-MiniGUI-4.0.md) -
Enhancements and changes of MiniGUI 4.0.x.
* [Writing DRI Engine Driver for Your GPU](Writing-DRI-Engine-Driver-for-Your-GPU.md) -
Writing a DRI engine driver to exploit the hardware accelerated functions of your GPU.
* [Supporting and Using Extra Input Messages](Supporting-and-Using-Extra-Input-Messages.md) -
Supporting and using extra input messages.
* [Using Enhanced Font Interfaces](Using-Enhanced-Font-Interfaces.md) -
Understand and use enhanced font intefaces of MiniGUI 4.0.
* [Showing Text in Complex/Mixed Scripts](Showing-Text-in-Complex-or-Mixed-Scripts.md) -
How to lay out, shape, and render text in complex or mixed scripts.
## Features for Version 3.2 or later
* [Release Notes for MiniGUI 3.2](Release-Notes-for-MiniGUI-3.2.md) -
Enhancements and changes of MiniGUI 3.2.x.
* [Using CommLCD NEWGAL Engine and Comm IAL Engine](Using-CommLCD-NEWGAL-Engine-and-Comm-IAL-Engine.md) -
How to define external stubs to implement your CommLCD engine and Comm
IAL engine outside MiniGUI Core.
* [Using Images and Fonts on System without File System](Using-Images-and-Fonts-on-System-without-File-System.md) -
How to build source for incore images and fonts, and load them for
your MiniGUI apps.
* [Using SyncUpdateDC to Reduce Screen Flicker](Using-SyncUpdateDC-to-Reduce-Screen-Flicker.md) -
How to use MiniGUI's synchronous update mechanism to reduce screen flicker.
* [Writing MiniGUI Apps for 64-bit Platforms](Writing-MiniGUI-Apps-for-64-bit-Platforms.md) -
Describe the things you need to be aware of when developing MiniGUI apps for 64-bit platforms.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
_Understand and use enhanced font intefaces of MiniGUI 4.0._
Table of Contents
- [Overview](#overview)
- [Enhancements of Font Name](#enhancements-of-font-name)
* [Devfont name](#devfont-name)
* [Logfont name](#logfont-name)
* [Font style](#font-style)
- [API Enhancements](#api-enhancements)
- [Example](#example)
## Overview
In order to support complex or mixed scripts, we tuned and enhanced
MiniGUI's font interfaces in version 4.0.0.
Before we continue, we need to clarify a few terms and concepts:
- `devfont`: a device font object. It is the underlying object
containing the glyphs of all or some characters in specific
language or script.
- `logfont`: a logical font object. It is the real object used by
MiniGUI app to render paragraphs, words, or characters.
Generally, a MiniGUI app creates one or more logfonts by specifying
the family, style, size, and charset/encoding, and calls GDI functions
to lay out, shape, and render the text.
When creating a logfont object, MiniGUI retrieves the devfonts which
matched the family, style, size, and character/encoding for the
requested logfont object in the devfonts base, which is loaded in
the start stage of MiniGUI.
However, one logfont object does not always correspond to a
devfont object, but rather to multiple devfont objects.
For example, when we want to show a text like below:
```
“对暴徒仁慈就是对良民的残忍”
-- Anonym
```
It is well known that, a font is often designed for a particular
language/script or a few similar languages/scripts.
So MiniGUI may retrieve the glyphs for the characters in the first line
(they are all in Chinese) in a font file named `宋体.ttf`, while in another
font file named `Arial.ttf` for the characters in the second line (they
are all in English).
Therefore, a logfont object actually corresponds to a collection of
devfont objects, which match the logfont's family, style, size, and
charset/encoding.
Before version 4.0.0, a logfont object can be represented by one or
two devfont objects. Therefore, MiniGUI can easily handle standard
languages/scripts, like Chinese, Japanese, English (Latin).
However, when we want to handle a text in the complex and mixed scripts
like Arabic and Indic, the old logfont/devfont facility will not work.
Therefore, we tuned and enhanced the font interfaces in version 4.0.0.
But don't worry, the tuned or enhanced interfaces kept the backward
compatibility.
## Enhancements of Font Name
### Devfont name
You know that we often use a string to specify the family name,
style, size, and charsets of a devfont object:
```
ttf-Arial-rrncnn-0-0-ISO8859-1,UTF-8
```
It means that the devfont is a TrueType vector font, the family name
of the devfont is `Arial`, the style is represented by a string `rrncnn`,
the size can be any value (e vector font can be arbitrarily scaled to
meet different size requirements.), and the charsets/encodings of the
devfont are `ISO8859-1` and `UTF-8`.
Since 4.0.0, you can specify the aliases for the family name of a devfont:
```
<fonttype>-<family[,aliase]*>-<styles>-<width>-<height>-<charset[,charset]*>
```
For example:
ttf-Arial,Sans Serif-rrncnn-0-0-ISO8859-1,UTF-8
ttf-courier,monospace,serif-rrncnn-0-0-ISO8859-1,UTF-8
Note that the length of one devfont name can not exceed 255 bytes.
### Logfont name
When we create a logfont object, we generally call `CreateLogFontByName`
function. The logfont name uses the similar format as devfont name:
```
<fonttype>-<family-name[,family-nameN]*>-<styles>-<width|orientation>-<height>-charset
```
Since version 4.0.0, you can specify up to 7 family names for a
logfont name, for example:
```
ttf-Courier,宋体,Naskh,SansSerif-rrncns-U-16-UTF-8
```
In this way, you can specify a logfont to use multiple devfonts
to render a complex text.
Moreover, the previous width field of a logfont name is used for
the glyph orientation:
- `U`: Glyphs stand upright (default).
- `S`: Glyphs are rotated 90 degrees clockwise (sideways).
- `D`: Glyphs are upside-down.
- `L`: Glyphs are rotated 90 degrees counter-clockwise (sideways left).
### Font style
As you seen in above font names, we use a style string (six ASCII characters)
to define the style of a font in font name.
In version 4.0.0, we tuned the meaning of each character in the style string.
The format of the style string changed from
```
<weight><slant><flipping><other><underline><struckout>
```
to
```
<weight><slant><flipping><other><decoration><rendering>
```
The differences are as follow:
- The new `<rendering>` style added.
- `<underline>` and `<struckout>` are merged to `<decoration>`
in order to keep the style string is still 6-character long.
- For `<weight>`, we redefined the weight styles follow OpenType specification.
The following words describe the detailed information about the changes of style:
- Introduced new rendering style:
1. `FS_RENDER_MONO`: represented by ASCII character `n`.
1. `FS_RENDER_GREY`: represented by ASCII character `g`.
1. `FS_RENDER_SUBPIXEL`: represented by ASCII character `s`.
* The following old styles are deprecated:
1. `FS_WEIGHT_BOOK`; use `FS_RENDER_GREY` instead.
1. `FS_WEIGHT_SUBPIXEL`; use `FS_RENDER_SUBPIXEL` instead.
* Introduced New weight style:
1. `FONT_WEIGHT_THIN`: Thin; represented by ASCII character `t`.
1. `FONT_WEIGHT_EXTRA_LIGHT`: Extra light (Ultra Light); represented by ASCII character `e`.
1. `FONT_WEIGHT_LIGHT`: Light; represented by ASCII character `l`.
1. `FONT_WEIGHT_NORMAL`: Normal; represented by ASCII character `n`.
1. `FONT_WEIGHT_REGULAR`: Regular; represented by ASCII character `r`.
1. `FONT_WEIGHT_MEDIUM`: Medium; represented by ASCII character `m`.
1. `FONT_WEIGHT_DEMIBOLD`: Demi Bold (Semi Bold); represented by ASCII character `d`.
1. `FONT_WEIGHT_BOLD`: Bold; represented by ASCII character `b`.
1. `FONT_WEIGHT_EXTRA_BOLD`: Extra Bold (Ultra Bold); represented by ASCII character `x`.
1. `FONT_WEIGHT_BLACK`: Black (Heavy); represented by ASCII character `c`.
* Introduce the new decoration styles and replace `FONT_UNDERLINE_LINE` and `FONT_STRUCKOUT_LINE` with them:
1. `FONT_DECORATE_NONE`: without any decoration; represented by ASCII character `n`.
1. `FONT_DECORATE_UNDERLINE`: glyphs are underscored represented by ASCII character `u`.
1. `FONT_DECORATE_STRUCKOUT`: glyphs are overstruck represented by ASCII character `s`.
1. `FONT_DECORATE_US`: Both `FONT_DECORATE_UNDERLINE` and `FONT_DECORATE_STRUCKOUT`; represented by ASCII character `U`.
1. `FONT_DECORATE_REVERSE`: Glyphs have their foreground and background reversed (`r`); Reserved for future.
1. `FONT_DECORATE_OUTLINE`: Outline (hollow) glyphs (`o`); Reserved for future.
* The following style are deprecated:
1. `FONT_OTHER_LCDPORTRAIT`
1. `FONT_OTHER_LCDPORTRAITKERN`
As an example, if you want to use the rendering method SUPIXEL for a TTF font,
please define the logfont name in the following way:
```
ttf-Courier-rrncns-*-16-UTF-8
```
## API Enhancements
For a new app, you should use the new function `CreateLogFontEx` to
create a logfont, and specify the weight and rendering method of the glyph:
```cpp
m_btnFont = CreateLogFontEx ("ttf", "helvetica", "UTF-8",
FONT_WEIGHT_REGULAR,
FONT_SLANT_ROMAN,
FONT_FLIP_NONE,
FONT_OTHER_NONE,
FONT_DECORATE_NONE, FONT_RENDER_SUBPIXEL,
SETTING_OK_BTN_TEXT_H, 0);
```
For the backward compatibility, you can still use `CreateLogFont` to create a new
logfont. However, `FS_WEIGHT_BOOK` will be treated `FS_WEIGHT_REGULAR` and
`FS_RENDER_GREY`, while `FS_WEIGHT_SUBPIXEL` will be treated
`FS_WEIGHT_REGULAR` and `FS_RENDER_SUBPIXEL`.
You can still use `CreateLogFontByName` to create a new logfont. But you should
make sure to define the new logfont name in new format.
We also introduced the following new functions in version 4.0.0:
- `CreateLogFontIndirectEx`: to create a new logfont object by using the properties
of an existing logfont object, but with a new rotation argument. This function is
a supplementary of `CreateLogFontIndirect`.
- `CreateLogFontForMChar2UChar`: to create a logfont in order to convert a multi-byte
character string to `Uchar32` string.
- `LoadDevFontFromIncoreData`: to load a devfont from a file. This function is
a supplementary of `LoadDevFontFromFile`.
## Example
For complete usage example of new font API, you can refer to:
<https://github.com/VincentWei/mg-tests/blob/master/4.0/createlogfontex.c>
_How to build source for incore images and fonts, and load them for your MiniGUI apps._
Table of Contents
- [Overview](#overview)
- [Tools for Generating Incore Data](#tools-for-generating-incore-data)
- [APIs for Managing Incore Data](#apis-for-managing-incore-data)
- [Restrictions](#restrictions)
## Overview
We often want to embed the raw data of images and/or fonts into the final executable
of a MiniGUI app:
- The operating system does not provide support for file system.
- You want to protect your digital intellectual properties such as icons.
For this purpose, MiniGUI provides a set of APIs and tools to embed the arbitrary
data into the final executable.
Note that, in MiniGUI term, we often call the embedded data as `incore data`,
`incore resource`, or `inner resource`.
For a complete sample, please refer to:
<https://github.com/VincentWei/mg-samples/tree/master/incore-data>
## Tools for Generating Incore Data
We provide some tools in [mg-tools](https://github.com/VincentWei/mg-tools)
to generate the source file for your incore data:
- `bin2c`: this is a general tool for generating any binary file to a
C source file. This tool generates a `unsigned char` array for your
program.
- `vbf2c`: this tool generates a `VBFINFO` struct from a MiniGUI VBF font
file for your program.
- `upf2c`: this tool generates a `UPFINFO` struct from a MiniGUI UPF font
file for your program. It also generates an external function to return
the pointer to the struct instead of exporting a global symbol of
the struct name.
To generate an incore source file for a UPF file, you can call `upf2c`:
```shell
$ upf2c res/unifont_160_50.upf unifont_160_50
```
This command will generate a source file named `unifont_160_50.c`:
```cpp
/*
** In-core UPF file for upf_unifont_160_50.
**
** This file is created by 'upf2c'
** Please do not modify it manually.
**
*/
#include <minigui/common.h>
#include <minigui/minigui.h>
#include <minigui/gdi.h>
#ifdef _MGFONT_UPF
typedef struct
{
Uint8 width;
Uint8 height;
Sint8 ascent;
Sint8 descent;
Uint8 max_width;
Uint8 underline_pos;
Uint8 underline_width;
Sint8 leading;
Uint8 mono_bitmap;
Uint8 reserved[3];
const void* root_dir;
Uint32 file_size;
} UPFINFO;
static const unsigned char font_data[] = {
...
};
static const UPFINFO upf_unifont_160_50 = {
0, 0, 0, 0, 0, 0, 0, 0, 0, {0, 0, 0},
font_data, sizeof (font_data)
};
const void* get_incore_font_data_upf_unifont_160_50 (void)
{
return &upf_unifont_160_50;
}
#endif /* _MGFONT_UPF */
```
To generate the source file for incore images or RBF fonts, you can use
`bin2c`:
```shell
$ bin2c -o png_pics.inc res/*.png
```
This command will generate a large C source file which defines
some `unsigned char` arrays for the PNG files in `res/` subdirectory,
one array for each file:
```cpp
static const unsigned char _png__mguxdemo_10_data[] = {
...
};
static const unsigned char _png__mguxdemo_11_data[] = {
...
};
```
The variable name for one file is consisted with the file name and
the `_png__` prefix and `_data` suffix.
## APIs for Managing Incore Data
For fonts and images, MiniGUI provides the basic API to load them from
incore data:
```cpp
DEVFONT* GUIAPI LoadDevFontFromIncoreData (const char *devfont_name,
const void *data);
void GUIAPI DestroyDynamicDevFont (DEVFONT **devfont);
int GUIAPI LoadBitmapFromMem (HDC hdc, PBITMAP pBitmap,
const void* mem, int size, const char* ext);
void GUIAPI UnloadBitmap (PBITMAP pBitmap);
```
For fonts, you should load an incore font before using the font,
generally before creating any main window, and destroy the font
before exiting MiniGUI:
```cpp
#define FONTNAME_UNIFONT_160_50 "upf-unifont-rrncnn-16-16-UTF-8"
static DEVFONT* devfont_unifont_160_50;
...
// Load incore font to create a devfont object
if ((devfont_unifont_160_50 = LoadDevFontFromIncoreData(
FONTNAME_UNIFONT_160_50,
get_incore_font_data_upf_unifont_160_50())) == NULL) {
_ERR_PRINTF("Failed to load incore UPF font.\n");
exit (1);
}
// use the devfont by creating a logfont object
logfont = CreateLogFontByName("upf-unifont-rrncnn-16-16-UTF-8");
...
// Destroy devfont object of the incore font
DestroyDynamicDevFont(&devfont_unifont_160_50);
```
For incore images, you can use the basic functions (`LoadBitmapFromMem`
and `UnloadBitmap`) to load and destroy the BITMAP object. Or you can
use the MiniGUI resource manager to manage the objects by using the
reference count mechanism.
By using the MiniGUI resource manager, you can use the original
file name to load a resource from incore resource. If there is
an incore resource for the specific file name, the resource manager
will load it from the incore resource, otherwise it will try to
load if from the file. On the other hand, the resource manager
will maintain a reference count for every loaded resource,
and really release the object only if the reference count reached 0.
In this way, you can avoid some bugs about object life cycle.
The sample uses the resource manager to maintain the incore images:
```cpp
#include "png_pics.inc"
static INNER_RES incore_pngs [] = {
{ 0, _png__mguxdemo_1_data, sizeof(_png__mguxdemo_1_data),
"res/mguxdemo-1.png" },
{ 0, _png__mguxdemo_2_data, sizeof(_png__mguxdemo_2_data),
"res/mguxdemo-2.png" },
{ 0, _png__mguxdemo_3_data, sizeof(_png__mguxdemo_3_data),
"res/mguxdemo-3.png" },
{ 0, _png__mguxdemo_4_data, sizeof(_png__mguxdemo_4_data),
"res/mguxdemo-4.png" },
{ 0, _png__mguxdemo_5_data, sizeof(_png__mguxdemo_5_data),
"res/mguxdemo-5.png" },
{ 0, _png__mguxdemo_6_data, sizeof(_png__mguxdemo_6_data),
"res/mguxdemo-6.png" },
{ 0, _png__mguxdemo_7_data, sizeof(_png__mguxdemo_7_data),
"res/mguxdemo-7.png" },
{ 0, _png__mguxdemo_8_data, sizeof(_png__mguxdemo_8_data),
"res/mguxdemo-8.png" },
{ 0, _png__mguxdemo_9_data, sizeof(_png__mguxdemo_9_data),
"res/mguxdemo-9.png" },
{ 0, _png__mguxdemo_10_data, sizeof(_png__mguxdemo_10_data),
"res/mguxdemo-10.png" },
{ 0, _png__mguxdemo_11_data, sizeof(_png__mguxdemo_11_data),
"res/mguxdemo-11.png" },
{ 0, _png__mguxdemo_12_data, sizeof(_png__mguxdemo_12_data),
"res/mguxdemo-12.png" },
{ 0, _png__mguxdemo_13_data, sizeof(_png__mguxdemo_13_data),
"res/mguxdemo-13.png" },
};
...
// add the incore resource to MiniGUI resource manager
for (i = 0; i < TABLESIZE(incore_pngs); i++) {
incore_pngs[i].key = Str2Key(incore_pngs[i].additional);
incore_pngs[i].additional = "png";
}
if (AddInnerRes(incore_pngs, TABLESIZE(incore_pngs), FALSE)
!= RES_RET_OK) {
_ERR_PRINTF("Failed to add incore PNG files.\n");
exit (1);
}
...
// load BITMAP object by using the file name
bmp = LoadBitmapFromRes(hdc, "res/mguxdemo-11.png");
if (bmp == NULL) {
_ERR_PRINTF("Failed to loaded png picture: %s\n", png_file_name);
return;
}
// use the BITMAP object
...
// Release resource
ReleaseRes(Str2Key("res/mguxdemo-11.png"));
...
// release the resource eventually
for (i = 0; i < TABLESIZE(incore_pngs); i++) {
ReleaseRes(incore_pngs[i].key);
}
```
## Restrictions
Note that, currently, MiniGUI does not support incore TrueType fonts.
_How to use MiniGUI's synchronous update mechanism to reduce screen flicker._
Table of Contents
- [Overview](#overview)
- [Principle](#principle)
- [Usage](#usage)
- [Restrictions](#restrictions)
## Overview
In the development of a GUI app, we often need to update an area on the
screen multiple times just for a user input. For example, if the user
presses the up and down keys, the highlighted item in the list box will
change. At this point, the program should perform the following operations:
1. Erase the original highlighted item with the background color of
a normal item;
1. Draw the text of the original highlighted item with the foreground
color of the normal item;
1. Erase the new highlighted item with the background color of the
highlighted item;
1. Draw the text of the new highlighted item with the foreground color
of the highlighted item.
This frequent drawing will cause the screen to flicker if we don't do
any special processing.
Generally, we can use one of the following ways to eliminate this flicker:
1. Create a memory DC and draw content to the memory DC first, then
call `BitBlt` to blit the content to screen.
1. Use MiniGUI's double buffer main window. This is essentially the
same as the first method.
1. Use the new synchronous update mechanism introduced in MiniGUI 3.2.x.
This documents describes how to use the new synchronous update mechanism
to reduce the screen flicker.
## Principle
Essentially, the new synchronous update mechanism uses a shadow frame
buffer for MiniGUI, and refresh the content that needs to be updated to
the screen at one time, by calling `SyncUpdateDC` function.
In this way, we do not need to create and destroy memory DC frequently,
so we will get a certain degree of performance improvement.
And the MiniGUI app's code can keep as simple as possible.
In other words, we can improve the maintainability of the code as well.
## Usage
- Including option `--enable-syncupdate` when configuring MiniGUI.
- Using a shadow-like NEWGAL engine and implementing `UpdateRects` method
of your NEWGAL engine to update the dirty regions to your real
screen frame buffer.
- Calling `SyncUpdateDC(HDC_SCREEN)` when you want to update the
screen. Generally, you can call this function after calling `EndPaint`
function when handling `MSG_PAINT` message.
## Sample
## Restrictions
The synchronous update mechanism provides an easy way to reduce
the screen flicker. However, it has the following restrictions:
- It is not suitable to a screen with high resolution.
- It may hide the side effects of some inefficient code in
your MiniGUI app.
- It lacks support for hardware acceleration.
Therefore, for modern graphics stack (system shipped with a GPU),
the better way is using off-screen surface and exploiting the
hardware acceleration as far as possible.
This diff is collapsed.
_Describe the things you need to be aware of when developing MiniGUI apps for 64-bit platforms._
Table of Contents
- [Overview](#overview)
- [Changes of Data Types](#changes-of-data-types)
* [Changes of handle types](#changes-of-handle-types)
* [Changes of integer types](#changes-of-integer-types)
* [New integer types](#new-integer-types)
- [API changes](#api-changes)
* [Integer macros](#integer-macros)
* [Structures and functions](#structures-and-functions)
+ [Message](#message)
+ [Window callback procedure](#window-callback-procedure)
+ [Notification callback procedure](#notification-callback-procedure)
+ [Time and timer](#time-and-timer)
- [Writing Portable Code](#writing-portable-code)
* [Use correct data types](#use-correct-data-types)
* [Invalid pointer values](#invalid-pointer-values)
## Overview
In MiniGUI 3.2.0, we enhanced MiniGUI to support 64-bit platforms.
Although many embedded devices or IoT devices are still using 32-bit
processors, we often need to develope MiniGUI apps on a desktop computer
(almost all desktop computer are now using 64-bit CPU), and then build
the code for the target system through a cross compiler. Therefore,
the code of a MiniGUI App needs to be portable, regardless of whether
the target system is 32-bit or 64-bit, or even a big-endian or
little-endian system.
This document focuses on some of the changes that MiniGUI introduces to
support 64-bit systems and what you need to be aware of when writing
portable code.
## Changes of Data Types
### Changes of handle types
All handle types, including `GHANDLE`, `HWND`, `HDC`, etc.,
are now defined as aliases of `PVOID` (`typedef void* PVOID`).
You may need to check your code to reflect this change.
### Changes of integer types
The type of `DWORD` now has pointer precision. That is,
the size of `DWORD` will be 4 bytes on 32-bit platform, and 8 bytes on
64-bit platform.
Similarly, `WPARAM` and `LPARAM` now have pointer precision.
`WORD` and `SWORD` has a half of pointer precision. The size of these
two types is 2 bytes on 32-bit platform, and 4 bytes on 64-bit platform.
`RGBCOLOR` now is defined as an alias of `DWORD32` (see below).
Note that the type of `BYTE` always has the size of 8-bit on both