diff --git a/README.md b/README.md index 316dda6..24445a3 100644 --- a/README.md +++ b/README.md @@ -10,21 +10,10 @@ Documentation can be found [here](docs). # Target v1.1.0 TODO list - [x] Fix all remaining build warnings - [x] More advanced text options -- [x] Comprehensive C++ wrapper - [x] Triangulation that can handle simple inputs - [x] Add `const` to all read-only accesses - [x] Add special case to text functions for buffers with palette types - [ ] Check for other buffer type inconsistencies -- [ ] Complete C++ docs - - [ ] Images - - [ ] Examples - - [x] `buffer.md` - - [x] `drawing.md` - - [x] `matrix.md` - - [ ] `README.md` - - [ ] `shaders.md` - - [ ] `shapes.md` - - [ ] `textbox.md` - [x] Leave this box unchecked # Feature wishlist diff --git a/docs/README.md b/docs/README.md index 5b0330f..bce91fb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # PAX graphics documentation The PAX graphics stack is being developed for the [MCH2022 badge](https://bodge.team/docs/badges/mch2022/). -It's goal is to allow anyone to, in C and/or C++, use a powerful list of drawing features with good optimisation. +It's goal is to allow anyone to, in C, use a powerful list of drawing features with good optimisation. This library is the successor of the revised graphics API for [the old badge.team firmware](https://github.com/badgeteam/ESP32-platform-firmware). @@ -38,61 +38,6 @@ From the [C API overview](c/README.md): -# Mixing C and C++ APIs - -It is possible to use *both* the C API and C++ API at the same time. - -The C++ API accepts types from the C API where relevant. -Some other types can be implicitly converted. - - -## `pax_*vec2f` and related types - -These types have aliased names (`pax::Vec2f` for example) and added operators. - -They are fully backwards compatible and can thus be constructed in C++ and passed to C API functions. - - -## `pax_buf_t` - -Most C api functions use a `pax_buf_t *` parameter. - -There is an implicit conversion to `pax::Buffer`, the drawing API made of member functions. -This object becomes a **non-owning** reference (C-style `pax_buf_t` not destroyed when C++ `pax::Buffer` is destroyed). - -Example: -```c++ -extern pax_buf_t *graphics; -void myFunction() { - // Simple conversion that doesn't do any allocation. - pax::Buffer betterGraphics(graphics); - - // Example C++ API usage. - betterGraphics.drawCircle(10, 10, 50); -} -``` - -The opposite conversion direction is also possible: the function `pax::Buffer::getInternal` returns a **non-owning** pointer to the C-style `pax_buf_t`. - -Example: -```c++ -extern pax::Buffer betterGraphics; -void myFunction() { - // Simple conversion that doesn't do any allocation. - pax_buf_t *graphics = betterGraphics.getInternal(); - - // Example C API usage. - pax_draw_circle(graphics, 0xffff0000, 10, 10, 50); -} -``` - -## `pax_font_t *` - -The C++ api currently uses this type directly. -If this ever changes, there will be an implicit conversion to the C++ type. - - - # Build system In order to support multiple targets and platforms, the build system for PAX has grown somewhat complex. diff --git a/docs/c/README.md b/docs/c/README.md index bc01e14..25d16fb 100644 --- a/docs/c/README.md +++ b/docs/c/README.md @@ -1,15 +1,12 @@ # PAX graphics documentation: C API The PAX graphics stack is being developed for the [MCH2022 badge](https://bodge.team/docs/badges/mch2022/). -It's goal is to allow anyone to, in C and/or C++, use a powerful list of drawing features with good optimisation. +It's goal is to allow anyone to, in C, use a powerful list of drawing features with good optimisation. This library is the successor of the revised graphics API for [the old badge.team firmware](https://github.com/badgeteam/ESP32-platform-firmware). For supported platforms, [see this link](../supported-platforms.md). -## Note: This is documentation for the C API -**[The C++ API](../cpp/README.md) is recommended for new applications, but the C API will remain supported.** - ## PAX Docs overview - [Getting started](#getting-started) - [API overview](#api-overview) diff --git a/docs/pixelformat.md b/docs/pixelformat.md index 45d9a77..bb7de8e 100644 --- a/docs/pixelformat.md +++ b/docs/pixelformat.md @@ -70,9 +70,7 @@ Palette pixel types can have between 1 and 8 bits per pixel: There is no color conversion done, simply tructation. However, this does not mean that palette colors are simply one integer; -Palette colors are treated as *fully opaque* when alpha (bits 31-24) is nonzero, -otherwise the color is treated as *fully transparent*. -This allows for a bit more flexibility: Suppose you have some mandatory draw call but you can change the color. All you have to do is set alpha to 0 to effectively not draw anything. +Palette colors are treated as *fully opaque* the color index in within the range in the palette (which means N < M where N is color index and M is amount of palette entries). If it is not in this range, the color is treated as *fully transparent*. This means that a `pax_col_t` value of 0x10000 to 0xff0000 is treated as transparent by both ARGB and palette color math. ## Pixel types: RGB @@ -96,7 +94,7 @@ ARGB pixel types can have 4 to 32 bits per pixel | PAX_BUF_32_8888ARGB | 32 | 8 As ARGB is the type in which color math is performed, conversion is minimal; simply scaling the values to fit the new bits per channel. -Additionally, `PAX_BUF_32_8888ARGB` represents the same pixel type as the ARGB colors in `pax_col_t` (C API) and `pax::Color` (C++ API). +Additionally, `PAX_BUF_32_8888ARGB` represents the same pixel type as the ARGB colors in `pax_col_t` and no conversion is required. @@ -132,7 +130,7 @@ There is no exceptions for crossing rows; If the amount of columns is not in int The single-byte addressing method simply indexes bytes without further conversion. Finally, more than one byte means potential *endianness conversion*. -When `pax_buf_reversed(true)` (C API) or `pax::Buffer::reverseEndianness(true)` (C++ API) is called, +When `pax_buf_reversed(true)` is called, endianness conversion will happen on both reads from and writes to the pixel buffer. Depending on architecture, this can incur a few instructions worth of overhead.