docs: first version of gint image documentation (fr+en)
This commit is contained in:
parent
ae3a135a81
commit
3523a83bda
GPG Key ID:
1BBA026E13FC0495
|
|
@ -12,6 +12,11 @@ import gint
|
|||
from gint import *
|
||||
```
|
||||
|
||||
**Contents**
|
||||
- [Keyboard input](#keyboard-input)
|
||||
- [Drawing and rendering](#drawing-and-rendering)
|
||||
- [Differences with gint's C API](#differences-with-gints-c-api)
|
||||
|
||||
## Keyboard input
|
||||
|
||||
Reference headers: [`<gint/keyboard.h>`](https://gitea.planet-casio.com/Lephenixnoir/gint/src/branch/master/include/gint/keyboard.h) and [`<gint/keycodes.h>`](https://gitea.planet-casio.com/Lephenixnoir/gint/src/branch/master/include/gint/keycodes.h).
|
||||
|
|
@ -238,7 +243,7 @@ In PythonExtra, `dupdate()` also indicates a "switch to graphics mode". Due to c
|
|||
|
||||
`dgetpixel()` returns the color of a pixel. Note that `dgetpixel()` reads from VRAM, not from the display.
|
||||
|
||||
_Example ([`ex_draw1.py`](../../sh/ports/examples/ex_draw1.py))._
|
||||
_Example ([`ex_draw1.py`](../../ports/sh/examples/ex_draw1.py))._
|
||||
|
||||
```py
|
||||
from gint import *
|
||||
|
|
@ -279,13 +284,124 @@ dellipse(x1: int, y1: int, x2: int, y2: int, fill_color: int,
|
|||
|
||||
TODO: Example for `drect()`, `drect_border()`, `dline()`.
|
||||
|
||||
_Example ([`ex_circle.py`](../../sh/ports/examples/ex_circle.py))._
|
||||
_Example ([`ex_circle.py`](../../ports/sh/examples/ex_circle.py))._
|
||||
|
||||
 
|
||||
|
||||
### Image rendering functions
|
||||
|
||||
TODO
|
||||
```py
|
||||
dimage(x: int, y: int, img: image) -> None
|
||||
dsubimage(x: int, y: int, img: image, left: int, top: int, width: int, height: int) -> None
|
||||
```
|
||||
|
||||
**On black-and-white models**
|
||||
|
||||
```py
|
||||
image:
|
||||
.profile -> IMAGE_MONO | ...
|
||||
.width -> int
|
||||
.height -> int
|
||||
.data -> buffer-like
|
||||
|
||||
# Constructor
|
||||
image(profile: IMAGE_*, width: int, height: int, data: buffer-like) -> image
|
||||
```
|
||||
|
||||
Images on black-and-white models have either 2 or 4 colors (when the gray engine is enabled). Each image has a `.profile` field indicating the image format (the name "profile" comes from old gint versions), two fields `.width` and `.height` specifying its size, and a `.data` field providing direct access to pixel data.
|
||||
|
||||
The table below lists the four available formats.
|
||||
|
||||
| Format | Colors | Layers | Name in fxconv |
|
||||
|--------------------|---------------------------------|--------|----------------|
|
||||
| `IMAGE_MONO` | Black/white (2) | 1 | `mono` |
|
||||
| `IMAGE_MONO_ALPHA` | Black/white, transparent (3) | 2 | `mono_alpha` |
|
||||
| `IMAGE_GRAY` | Shades of gray (4) | 2 | `gray` |
|
||||
| `IMAGE_GRAY_ALPHA` | Shades of gray, transparent (5) | 3 | `gray_alpha` |
|
||||
|
||||
The raw storage format for data is a bit complicated. The image is stored in row-major order; each line is represented left-to-right by a series of words each covering 32 pixels. Each word contains one bit per pixel (as a 4-byte integer) for each layer.
|
||||
|
||||
The easiest way to obtain an image is to generate the associated code with the fxconv tool from the [fxSDK](https://gitea.planet-casio.com/Lephenixnoir/fxsdk). The options `--bopti-image-fx --fx` specify a conversion for black-and-white models and the metadata `profile:mono` selects the encoding. The table above lists the value of `profile:` to use for each desired format. For instance for [`fx_image_7seg.py`](../../ports/sh/examples/fx_image_7seg.png) :
|
||||
|
||||
|
||||
|
||||
```bash
|
||||
% fxconv --bopti-image fx_image_7seg.png -o 7seg.py --fx profile:mono name:seg --py
|
||||
```
|
||||
```py
|
||||
import gint
|
||||
seg = gint.image(0, 79, 12, b'|\x00||\x00|||||\x00\x00\xba\x02::\x82\xb8\xb8:\xba\xba\x00\x00\xc6\x06\x06\x06\xc6\xc0\xc0\x06\xc6\xc6\x00\x00\xc6\x06\x06\x06\xc6\xc0\xc0\x06\xc6\xc6\x00\x00\x82\x02\x02\x02\x82\x80\x80\x02\x82\x82\x00\x00\x00\x00|||||\x00||\x00\x00\x82\x02\xb8:::\xba\x02\xba:\x00\x00\xc6\x06\xc0\x06\x06\x06\xc6\x06\xc6\x06\x00\x00\xc6\x06\xc0\x06\x06\x06\xc6\x06\xc6\x06\x00\x00\xc6\x06\xc0\x06\x06\x06\xc6\x06\xc6\x06\x00\x00\xba\x02\xb8:\x02:\xba\x02\xba:\x00\x00|\x00||\x00||\x00||\x00\x00')
|
||||
```
|
||||
The option `--py-compact` generates much shorter code (less `\x`), however the resulting file can generally not be read or modified by a text editor. The only easy option to use that file is to send it to the calculator and import it as-is. (It can also by manipulated by a program if needed.)
|
||||
|
||||
`dimage()` renders an image, positioned so that the top-left corner of the image is located at (x, y).
|
||||
|
||||
`dsubimage()` renders a sub-rectangle of an image. The rectangle starts at position (left, top) within the image and is of size `width` by `height`. It is positioned so that the (left, top) pixel is drawn at (x, y) on the screen.
|
||||
|
||||
_Example ([`fx_image.py`](../../ports/sh/examples/fx_image.py))._
|
||||
|
||||
|
||||
|
||||
**On color models**
|
||||
|
||||
```py
|
||||
image:
|
||||
.format -> IMAGE_RGB565 | ...
|
||||
.flags -> int
|
||||
.color_count -> int
|
||||
.width -> int
|
||||
.height -> int
|
||||
.stride -> int
|
||||
.data -> buffer-like
|
||||
.palette -> buffer-like
|
||||
|
||||
# Constructor
|
||||
image(format: IMAGE_*, color_count: int, width: int, height: int, stride: int, data: buffer-like, palette: buffer-like) -> image
|
||||
|
||||
# Format-specific constructors
|
||||
image_rgb565(width: int, height: int, data: buffer-like) -> image
|
||||
image_rgb565a(width: int, height: int, data: buffer-like) -> image
|
||||
image_p8_rgb565(width: int, height: int, data: buffer-like, palette: buffer-like) -> image
|
||||
image_p8_rgb565a(width: int, height: int, data: buffer-like, palette: buffer-like) -> image
|
||||
image_p4_rgb565(width: int, height: int, data: buffer-like, palette: buffer-like) -> image
|
||||
image_p4_rgb565a(width: int, height: int, data: buffer-like, palette: buffer-like) -> image
|
||||
```
|
||||
|
||||
Images on color models are available in multiple formats as indicated by the `.format` field; the possible values are listed below. Formats differ in the number of colors, the presence of a transparent color, and the presence of a palette. Of course, the less colors the smaller the memory footprint of the image, so in general it is very beneficial to use the smallest format in which an image fits.
|
||||
|
||||
| Format | Colors | Palette | Name in fxconv |
|
||||
|--------------------|---------------------|-------------|----------------|
|
||||
| `IMAGE_RGB565` | 65536 | No | `rgb565` |
|
||||
| `IMAGE_RGB565A` | 65535 + transparent | No | `rgb565a` |
|
||||
| `IMAGE_P8_RGB565` | 256 | Yes (1-256) | `p8_rgb565` |
|
||||
| `IMAGE_P8_RGB565A` | 255 + transparent | Yes (1-256) | `p8_rgb565a` |
|
||||
| `IMAGE_P4_RGB565` | 16 | Yes (16) | `p4_rgb565` |
|
||||
| `IMAGE_P4_RGB565A` | 15 + transparent | Yes (16) | `p4_rgb565a` |
|
||||
|
||||
The `.color_count` field indicates the number of colors in the palette, when there is one. For P8 formats this number varies between 1 and 256, and for P4 formats it is always equal to 16. The `.width` and `.height` fields indicate the image's size. Finally, the `.data` and `.palette` fields provide direct access to the raw data for the image's pixels and color palette.
|
||||
|
||||
(The `.flags` field has details of memory management that shouldn't be important to Python scripts. The `.stride` fields indicates the distance in bytes between rows of pixels in `.data` and should similarly be of rare use.)
|
||||
|
||||
The functions `dimage()` and `dsubimage()` work the same way as for black-and-white models; please see above.
|
||||
|
||||
As for black-and-white models, images can be converted into a Python format with fxconv. For instance with [`cg_image_puzzle.png`](../../ports/sh/examples/cg_image_puzzle.png)
|
||||
|
||||
|
||||
|
||||
```bash
|
||||
% fxconv --bopti-image cg_image_puzzle.png -o puzzle.py --cg profile:p4_rgb565 name:puzzle --py
|
||||
```
|
||||
```py
|
||||
import gint
|
||||
puzzle = gint.image(6, 16, 64, 32, 32,
|
||||
b'\xbb\xbb\xbb\xbb\xbb ... \xdd\xdd\xdd\xdd\xdd\xdd\xdd',
|
||||
b'\xff\xff\xcfW\x86\xd8\xbe|\xceP\xe5\x8a\x963f9u\x9c}\xa8\x9dxD\xfa\x83\xceLNZ\xcci\xa7')
|
||||
```
|
||||
The option `--py-compact` is recommended to reduce code size; please see details in the black-and-white section above.
|
||||
|
||||
_Exemple ([`cg_image.py`](../../ports/sh/examples/cg_image.py))._
|
||||
|
||||
|
||||
|
||||
## Differences with gint's C API
|
||||
|
||||
|
|
|
|||
|
|
@ -12,6 +12,11 @@ import gint
|
|||
from gint import *
|
||||
```
|
||||
|
||||
**Sommaire**
|
||||
- [Saisie au clavier](#saisie-au-clavier)
|
||||
- [Dessin à l'écran](#dessin-à-lécran)
|
||||
- [Différences avec l'API C de gint](#différences-avec-lapi-c-de-gint)
|
||||
|
||||
## Saisie au clavier
|
||||
|
||||
Les en-têtes de référence sont [`<gint/keyboard.h>`](https://gitea.planet-casio.com/Lephenixnoir/gint/src/branch/master/include/gint/keyboard.h) et [`<gint/keycodes.h>`](https://gitea.planet-casio.com/Lephenixnoir/gint/src/branch/master/include/gint/keycodes.h).
|
||||
|
|
@ -315,9 +320,9 @@ Les quatre formats disponibles sont les suivants.
|
|||
| `IMAGE_GRAY` | Niveaux de gris (4) | 2 | `gray` |
|
||||
| `IMAGE_GRAY_ALPHA` | Niveaux de gris, transparent (5) | 3 | `gray_alpha` |
|
||||
|
||||
Le format des données brutes est un peu compliqué. Il y a un ou plusieurs calques, chacun stocké ligne par ligne de haut en bas ; chaque ligne est représentée de gauche à droite avec un bit par pixel, arrondi au multiple supérieur de 32 bits (4 octets).
|
||||
Le format des données brutes est un peu compliqué. L'image est stockée ligne par ligne de haut en bas ; chaque ligne est représentée de gauche à droite par une série de mots représentant chacun 32 pixels. Chaque mot contient un bit par pixel (sous la forme d'un entier de 4 octets) pour chaque calque.
|
||||
|
||||
Le plus simple pour obtenir une image est de générer le code associé avec l'outil fxconv du [fxSDK](https://gitea.planet-casio.com/Lephenixnoir/fxsdk). Les options `--bopti-image-fx --fx` spécifient qu'on convertit une image pour Graph mono et la métadonnée `profile:mono` choisit le format de l'image produite. Le tableau ci-dessus list la valeur de `profile:` à spécifier pour chaque format. Exemple pourl'image [`fx_image_7seg.py`](../../ports/sh/examples/fx_image_7seg.png) :
|
||||
Le plus simple pour obtenir une image est de générer le code associé avec l'outil fxconv du [fxSDK](https://gitea.planet-casio.com/Lephenixnoir/fxsdk). Les options `--bopti-image-fx --fx` spécifient qu'on convertit une image pour Graph mono et la métadonnée `profile:mono` choisit le format de l'image produite. Le tableau ci-dessus liste la valeur de `profile:` à spécifier pour chaque format. Par exemple pour l'image [`fx_image_7seg.py`](../../ports/sh/examples/fx_image_7seg.png) :
|
||||
|
||||
|
||||
|
||||
|
|
@ -328,9 +333,13 @@ Le plus simple pour obtenir une image est de générer le code associé avec l'o
|
|||
import gint
|
||||
seg = gint.image(0, 79, 12, b'|\x00||\x00|||||\x00\x00\xba\x02::\x82\xb8\xb8:\xba\xba\x00\x00\xc6\x06\x06\x06\xc6\xc0\xc0\x06\xc6\xc6\x00\x00\xc6\x06\x06\x06\xc6\xc0\xc0\x06\xc6\xc6\x00\x00\x82\x02\x02\x02\x82\x80\x80\x02\x82\x82\x00\x00\x00\x00|||||\x00||\x00\x00\x82\x02\xb8:::\xba\x02\xba:\x00\x00\xc6\x06\xc0\x06\x06\x06\xc6\x06\xc6\x06\x00\x00\xc6\x06\xc0\x06\x06\x06\xc6\x06\xc6\x06\x00\x00\xc6\x06\xc0\x06\x06\x06\xc6\x06\xc6\x06\x00\x00\xba\x02\xb8:\x02:\xba\x02\xba:\x00\x00|\x00||\x00||\x00||\x00\x00')
|
||||
```
|
||||
L'option `--py-compact` permet de générer du code beaucoup plus compact (avec moins de `\x`), par contre le fichier obtenu ne peut pas être lu par un éditeur de texte. La seule option simple pour l'utiliser est de l'envoyer sur la calculatrice et l'installer inchangé (on peut aussi le manipuler avec un programme).
|
||||
L'option `--py-compact` permet de générer du code beaucoup plus compact (avec moins de `\x`), par contre le fichier obtenu ne peut pas être lu par un éditeur de texte. La seule option simple pour l'utiliser est de l'envoyer sur la calculatrice et l'importer tel quel (on peut aussi le manipuler avec un programme).
|
||||
|
||||
_Exemple ([`fx_image.py`](../../sh/ports/examples/fx_image.py))._
|
||||
La fonction `dimage()` dessine une image à l'écran en positionnant le coin haut gauche de l'image à la position (x, y).
|
||||
|
||||
La fonction `dsubimage()` permet de dessiner un sous-rectangle d'une image. Le sous-rectangle commence à la position (left, top) de l'image et s'étend sur une largeur `width` et une hauteur `height`. Le sous-rectangle est dessiné de façon à ce que le pixel (left, top) arrive à la position (x, y) de l'écran.
|
||||
|
||||
_Exemple ([`fx_image.py`](../../ports/sh/examples/fx_image.py))._
|
||||
|
||||
|
||||
|
||||
|
|
@ -346,6 +355,17 @@ image:
|
|||
.stride -> int
|
||||
.data -> buffer-like
|
||||
.palette -> buffer-like
|
||||
|
||||
# Constructeur
|
||||
image(format: IMAGE_*, color_count: int, width: int, height: int, stride: int, data: buffer-like, palette: buffer-like) -> image
|
||||
|
||||
# Constructeurs spécialisés par format
|
||||
image_rgb565(width: int, height: int, data: buffer-like) -> image
|
||||
image_rgb565a(width: int, height: int, data: buffer-like) -> image
|
||||
image_p8_rgb565(width: int, height: int, data: buffer-like, palette: buffer-like) -> image
|
||||
image_p8_rgb565a(width: int, height: int, data: buffer-like, palette: buffer-like) -> image
|
||||
image_p4_rgb565(width: int, height: int, data: buffer-like, palette: buffer-like) -> image
|
||||
image_p4_rgb565a(width: int, height: int, data: buffer-like, palette: buffer-like) -> image
|
||||
```
|
||||
|
||||
Les images sur Graph couleur sont déclinées en différents formats indiqués par le champ `.format`, dont les valeurs possibles sont listées ci-dessous. Les différences sont dans le nombre de couleurs, la présence ou pas de transparence, et la présence ou pas d'une palette de couleurs. Bien sûr, moins il y a de couleurs moins l'image prend de place en mémoire, donc de façon générale il est très bénéfique d'utiliser le plus petit format possible pour chaque image.
|
||||
|
|
@ -359,13 +379,28 @@ Les images sur Graph couleur sont déclinées en différents formats indiqués p
|
|||
| `IMAGE_P4_RGB565` | 16 | Oui (16) | `p4_rgb565` |
|
||||
| `IMAGE_P4_RGB565A` | 15 + transparent | Oui (16) | `p4_rgb565a` |
|
||||
|
||||
Le champ `.color_count` indique le nombre de couleurs dans la palette quand il y en a une. Pour les formats P8 ce nombre varie entre 1 et 256, pour les formats P4 il est toujours égal à 16. Les deux champs `.width` et `.height` indiquent la taille de l'image. Enifn, les champs `.data` et `.palette` permettent d'accéder aux données brutes des pixels ainsi que de la palette.
|
||||
Le champ `.color_count` indique le nombre de couleurs dans la palette quand il y en a une. Pour les formats P8 ce nombre varie entre 1 et 256, pour les formats P4 il est toujours égal à 16. Les deux champs `.width` et `.height` indiquent la taille de l'image. Enfin, les champs `.data` et `.palette` permettent d'accéder aux données brutes des pixels ainsi que de la palette.
|
||||
|
||||
(Le champ `.flags` est un détail de gestion de mémoire qui ne devrait pas importer aux scripts Python. Le champ `.stride` indique combien d'octets séparent chaque ligne de pixels dans `.data` et sera de même rarement utilisé.)
|
||||
|
||||
TODO
|
||||
Les fonctions `dimage()` et `dsubimage()` ont le même fonctionnement que pour les Graph mono ; voir ci-dessus.
|
||||
|
||||
_Exemple ([`cg_image.py`](../../sh/ports/examples/cg_image.py))._
|
||||
Comme pour Graph mono les images peuvent être converties avec fxconv. Par exemple pour l'image [`cg_image_puzzle.png`](../../ports/sh/examples/cg_image_puzzle.png)
|
||||
|
||||
|
||||
|
||||
```bash
|
||||
% fxconv --bopti-image cg_image_puzzle.png -o puzzle.py --cg profile:p4_rgb565 name:puzzle --py
|
||||
```
|
||||
```py
|
||||
import gint
|
||||
puzzle = gint.image(6, 16, 64, 32, 32,
|
||||
b'\xbb\xbb\xbb\xbb\xbb ... \xdd\xdd\xdd\xdd\xdd\xdd\xdd',
|
||||
b'\xff\xff\xcfW\x86\xd8\xbe|\xceP\xe5\x8a\x963f9u\x9c}\xa8\x9dxD\xfa\x83\xceLNZ\xcci\xa7')
|
||||
```
|
||||
L'option `--py-compact` est recommandée pour réduire la taille du code ; voir les détails dans la section Graph mono.
|
||||
|
||||
_Exemple ([`cg_image.py`](../../ports/sh/examples/cg_image.py))._
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue