awtk/docs/manual/bitmap_t.md

463 lines
13 KiB
Markdown
Raw Normal View History

2018-12-20 17:33:31 +08:00
## bitmap\_t
### 概述
2019-11-15 11:33:43 +08:00
位图。
2019-01-15 14:34:05 +08:00
----------------------------------
2018-12-20 17:33:31 +08:00
### 函数
<p id="bitmap_t_methods">
| 函数名称 | 说明 |
| -------- | ------------ |
2018-12-21 12:11:40 +08:00
| <a href="#bitmap_t_bitmap_create">bitmap\_create</a> | 创建图片对象(一般供脚本语言中使用)。 |
| <a href="#bitmap_t_bitmap_create_ex">bitmap\_create\_ex</a> | 创建图片对象。 |
| <a href="#bitmap_t_bitmap_destroy">bitmap\_destroy</a> | 销毁图片。 |
2020-12-08 09:04:40 +08:00
| <a href="#bitmap_t_bitmap_destroy_with_self">bitmap\_destroy\_with\_self</a> | 销毁图片(for script only)。 |
2018-12-21 12:11:40 +08:00
| <a href="#bitmap_t_bitmap_get_bpp">bitmap\_get\_bpp</a> | 获取图片一个像素占用的字节数。 |
2020-08-04 21:45:46 +08:00
| <a href="#bitmap_t_bitmap_get_bpp_of_format">bitmap\_get\_bpp\_of\_format</a> | 获取位图格式对应的颜色位数。 |
2018-12-21 12:11:40 +08:00
| <a href="#bitmap_t_bitmap_get_line_length">bitmap\_get\_line\_length</a> | 获取每一行占用内存的字节数。 |
| <a href="#bitmap_t_bitmap_get_pixel">bitmap\_get\_pixel</a> | 获取图片指定像素的rgba颜色值(主要用于测试程序)。 |
| <a href="#bitmap_t_bitmap_init">bitmap\_init</a> | 初始化图片。 |
2021-08-03 07:53:37 +08:00
| <a href="#bitmap_t_bitmap_init_from_bgra">bitmap\_init\_from\_bgra</a> | 初始化图片。 |
2019-12-14 13:25:56 +08:00
| <a href="#bitmap_t_bitmap_init_from_rgba">bitmap\_init\_from\_rgba</a> | 初始化图片。 |
2019-11-14 15:54:03 +08:00
| <a href="#bitmap_t_bitmap_lock_buffer_for_read">bitmap\_lock\_buffer\_for\_read</a> | 为读取数据而锁定bitmap的图片缓冲区。 |
| <a href="#bitmap_t_bitmap_lock_buffer_for_write">bitmap\_lock\_buffer\_for\_write</a> | 为修改数据而锁定bitmap的图片缓冲区。 |
2020-05-24 19:28:22 +08:00
| <a href="#bitmap_t_bitmap_mono_dump">bitmap\_mono\_dump</a> | dump mono bitmap。 |
| <a href="#bitmap_t_bitmap_save_png">bitmap\_save\_png</a> | 把bitmap保存为png。 |
2018-12-21 12:11:40 +08:00
| <a href="#bitmap_t_bitmap_set_line_length">bitmap\_set\_line\_length</a> | 设置line_length。 |
2019-11-14 15:54:03 +08:00
| <a href="#bitmap_t_bitmap_unlock_buffer">bitmap\_unlock\_buffer</a> | 解锁图像缓冲区。 |
2018-12-20 17:33:31 +08:00
### 属性
<p id="bitmap_t_properties">
2019-01-17 15:56:15 +08:00
| 属性名称 | 类型 | 说明 |
2018-12-20 17:33:31 +08:00
| -------- | ----- | ------------ |
2019-11-14 15:54:03 +08:00
| <a href="#bitmap_t_buffer">buffer</a> | graphic\_buffer\_t* | 图片数据。 |
2018-12-21 18:29:29 +08:00
| <a href="#bitmap_t_flags">flags</a> | uint16\_t | 标志。请参考{bitmap_flag_t}。 |
| <a href="#bitmap_t_format">format</a> | uint16\_t | 格式。请参考{bitmap_format_t}。 |
| <a href="#bitmap_t_h">h</a> | wh\_t | 高度。 |
| <a href="#bitmap_t_line_length">line\_length</a> | uint32\_t | 每一行实际占用的内存(也称为stride或pitch)一般情况下为w*bpp。 |
2019-05-07 14:37:26 +08:00
| <a href="#bitmap_t_name">name</a> | const char* | 名称。 |
2018-12-21 18:29:29 +08:00
| <a href="#bitmap_t_w">w</a> | wh\_t | 宽度。 |
2018-12-20 17:33:31 +08:00
#### bitmap\_create 函数
2018-12-21 18:29:29 +08:00
-----------------------
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_create">创建图片对象(一般供脚本语言中使用)。
2019-10-16 09:02:32 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
bitmap_t* bitmap_create ();
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | bitmap\_t* | 返回bitmap对象。 |
2018-12-21 18:29:29 +08:00
#### bitmap\_create\_ex 函数
-----------------------
2018-12-21 11:39:05 +08:00
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_create_ex">创建图片对象。
2019-10-16 09:02:32 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
bitmap_t* bitmap_create_ex (uint32_t w, uint32_t h, uint32_t line_length, bitmap_format_t format);
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | bitmap\_t* | 返回bitmap对象。 |
| w | uint32\_t | 宽度。 |
| h | uint32\_t | 高度。 |
| line\_length | uint32\_t | line\_length。 |
| format | bitmap\_format\_t | 格式。 |
2018-12-21 18:29:29 +08:00
#### bitmap\_destroy 函数
-----------------------
2018-12-21 11:39:05 +08:00
2018-12-21 18:29:29 +08:00
* 函数功能:
2018-12-20 17:33:31 +08:00
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_destroy">销毁图片。
2019-10-16 09:02:32 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
ret_t bitmap_destroy (bitmap_t* bitmap);
```
* 参数说明:
2020-12-08 09:04:40 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
#### bitmap\_destroy\_with\_self 函数
-----------------------
* 函数功能:
> <p id="bitmap_t_bitmap_destroy_with_self">销毁图片(for script only)。
* 函数原型:
```
ret_t bitmap_destroy_with_self (bitmap_t* bitmap);
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
2018-12-21 18:29:29 +08:00
#### bitmap\_get\_bpp 函数
-----------------------
2018-12-21 11:39:05 +08:00
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_get_bpp">获取图片一个像素占用的字节数。
2019-10-16 09:02:32 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
uint32_t bitmap_get_bpp (bitmap_t* bitmap);
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | uint32\_t | 返回一个像素占用的字节数。 |
| bitmap | bitmap\_t* | bitmap对象。 |
2020-08-04 21:45:46 +08:00
#### bitmap\_get\_bpp\_of\_format 函数
-----------------------
* 函数功能:
> <p id="bitmap_t_bitmap_get_bpp_of_format">获取位图格式对应的颜色位数。
* 函数原型:
```
uint32_t bitmap_get_bpp_of_format (bitmap_format_t format);
```
* 参数说明:
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | uint32\_t | 成功返回颜色位数失败返回0。 |
| format | bitmap\_format\_t | 位图格式。 |
2018-12-21 18:29:29 +08:00
#### bitmap\_get\_line\_length 函数
-----------------------
2018-12-21 11:39:05 +08:00
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_get_line_length">获取每一行占用内存的字节数。
2019-10-16 09:02:32 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
ret_t bitmap_get_line_length (bitmap_t* bitmap);
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
2018-12-29 12:17:06 +08:00
| 返回值 | ret\_t | 返回每一行占用内存的字节数。 |
2018-12-20 17:33:31 +08:00
| bitmap | bitmap\_t* | bitmap对象。 |
2018-12-21 18:29:29 +08:00
#### bitmap\_get\_pixel 函数
-----------------------
2018-12-21 11:39:05 +08:00
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_get_pixel">获取图片指定像素的rgba颜色值(主要用于测试程序)。
2019-10-16 09:02:32 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
ret_t bitmap_get_pixel (bitmap_t* bitmap, uint32_t x, uint32_t y, rgba_t* rgba);
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
| x | uint32\_t | x坐标。 |
| y | uint32\_t | y坐标。 |
| rgba | rgba\_t* | 返回颜色值。 |
2018-12-21 18:29:29 +08:00
#### bitmap\_init 函数
-----------------------
2018-12-21 11:39:05 +08:00
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_init">初始化图片。
2019-10-16 09:02:32 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
ret_t bitmap_init (bitmap_t* bitmap, uint32_t w, uint32_t h, bitmap_format_t format, const uint8_t* data);
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
| w | uint32\_t | 宽度。 |
| h | uint32\_t | 高度。 |
| format | bitmap\_format\_t | 格式。 |
| data | const uint8\_t* | 数据,直接引用,但不负责释放。如果为空,由内部自动分配和释放。 |
2021-08-03 07:53:37 +08:00
#### bitmap\_init\_from\_bgra 函数
-----------------------
* 函数功能:
> <p id="bitmap_t_bitmap_init_from_bgra">初始化图片。
数据。3通道时为BGR888格式4通道时为BGRA888格式(内部拷贝该数据,不会引用,调用者自行释放)。
* 函数原型:
```
ret_t bitmap_init_from_bgra (bitmap_t* bitmap, uint32_t w, uint32_t h, bitmap_format_t format, const uint8_t* , uint32_t comp);
```
* 参数说明:
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
| w | uint32\_t | 宽度。 |
| h | uint32\_t | 高度。 |
| format | bitmap\_format\_t | 格式。 |
| | const uint8\_t* | a |
| comp | uint32\_t | 颜色通道数(目前支持3(bgr)和4(bgra))。 |
2018-12-21 18:29:29 +08:00
#### bitmap\_init\_from\_rgba 函数
-----------------------
2018-12-21 11:39:05 +08:00
* 函数功能:
2019-12-14 13:25:56 +08:00
> <p id="bitmap_t_bitmap_init_from_rgba">初始化图片。
数据。3通道时为RGB888格式4通道时为RGBA888格式(内部拷贝该数据,不会引用,调用者自行释放)。
2018-12-20 17:33:31 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
ret_t bitmap_init_from_rgba (bitmap_t* bitmap, uint32_t w, uint32_t h, bitmap_format_t format, const uint8_t* , uint32_t comp);
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
| w | uint32\_t | 宽度。 |
| h | uint32\_t | 高度。 |
| format | bitmap\_format\_t | 格式。 |
| | const uint8\_t* | a |
| comp | uint32\_t | 颜色通道数(目前支持3(rgb)和4(rgba))。 |
2019-11-14 15:54:03 +08:00
#### bitmap\_lock\_buffer\_for\_read 函数
-----------------------
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_lock_buffer_for_read">为读取数据而锁定bitmap的图片缓冲区。
2019-11-14 15:54:03 +08:00
* 函数原型:
```
uint8_t* bitmap_lock_buffer_for_read (bitmap_t* bitmap);
```
* 参数说明:
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | uint8\_t* | 返回缓存区的首地址。 |
| bitmap | bitmap\_t* | bitmap对象。 |
#### bitmap\_lock\_buffer\_for\_write 函数
-----------------------
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_lock_buffer_for_write">为修改数据而锁定bitmap的图片缓冲区。
2019-11-14 15:54:03 +08:00
* 函数原型:
```
uint8_t* bitmap_lock_buffer_for_write (bitmap_t* bitmap);
```
* 参数说明:
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | uint8\_t* | 返回缓存区的首地址。 |
| bitmap | bitmap\_t* | bitmap对象。 |
2020-05-24 19:28:22 +08:00
#### bitmap\_mono\_dump 函数
-----------------------
* 函数功能:
> <p id="bitmap_t_bitmap_mono_dump">dump mono bitmap。
* 函数原型:
```
ret_t bitmap_mono_dump (const uint8_t* buff, uint32_t w, uint32_t h);
```
* 参数说明:
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| buff | const uint8\_t* | 数据。 |
| w | uint32\_t | 宽度。 |
| h | uint32\_t | 高度。 |
#### bitmap\_save\_png 函数
-----------------------
* 函数功能:
> <p id="bitmap_t_bitmap_save_png">把bitmap保存为png。
* 函数原型:
```
bool_t bitmap_save_png (bitmap_t* bitmap, const char* filename);
```
* 参数说明:
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | bool\_t | 返回TRUE表示成功FALSE表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
| filename | const char* | 文件名。 |
2018-12-21 18:29:29 +08:00
#### bitmap\_set\_line\_length 函数
-----------------------
2018-12-21 11:39:05 +08:00
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_set_line_length">设置line_length。
2019-10-16 09:02:32 +08:00
2018-12-21 11:39:05 +08:00
* 函数原型:
```
ret_t bitmap_set_line_length (bitmap_t* bitmap, uint32_t line_length);
```
* 参数说明:
2018-12-20 17:33:31 +08:00
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
| line\_length | uint32\_t | line\_length。 |
2019-11-14 15:54:03 +08:00
#### bitmap\_unlock\_buffer 函数
-----------------------
* 函数功能:
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_bitmap_unlock_buffer">解锁图像缓冲区。
2019-11-14 15:54:03 +08:00
* 函数原型:
```
ret_t bitmap_unlock_buffer (bitmap_t* bitmap);
```
* 参数说明:
| 参数 | 类型 | 说明 |
| -------- | ----- | --------- |
| 返回值 | ret\_t | 返回RET\_OK表示成功否则表示失败。 |
| bitmap | bitmap\_t* | bitmap对象。 |
#### buffer 属性
2018-12-20 17:33:31 +08:00
-----------------------
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_buffer">图片数据。
2019-10-16 09:02:32 +08:00
2019-11-14 15:54:03 +08:00
* 类型graphic\_buffer\_t*
2018-12-20 17:33:31 +08:00
| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
#### flags 属性
-----------------------
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_flags">标志。请参考{bitmap_flag_t}。
2019-10-16 09:02:32 +08:00
2018-12-20 17:33:31 +08:00
* 类型uint16\_t
| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
| 可脚本化 | 是 |
#### format 属性
-----------------------
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_format">格式。请参考{bitmap_format_t}。
2019-10-16 09:02:32 +08:00
2018-12-20 17:33:31 +08:00
* 类型uint16\_t
| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
| 可脚本化 | 是 |
#### h 属性
-----------------------
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_h">高度。
2019-10-16 09:02:32 +08:00
2018-12-20 17:33:31 +08:00
* 类型wh\_t
| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
| 可脚本化 | 是 |
#### line\_length 属性
-----------------------
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_line_length">每一行实际占用的内存(也称为stride或pitch)一般情况下为w*bpp。
2019-10-16 09:02:32 +08:00
2018-12-20 17:33:31 +08:00
* 类型uint32\_t
| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
| 可脚本化 | 是 |
#### name 属性
-----------------------
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_name">名称。
2019-10-16 09:02:32 +08:00
2019-05-07 14:37:26 +08:00
* 类型const char*
2018-12-20 17:33:31 +08:00
| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
| 可脚本化 | 是 |
#### w 属性
-----------------------
2019-11-15 11:33:43 +08:00
> <p id="bitmap_t_w">宽度。
2019-10-16 09:02:32 +08:00
2018-12-20 17:33:31 +08:00
* 类型wh\_t
| 特性 | 是否支持 |
| -------- | ----- |
| 可直接读取 | 是 |
| 可直接修改 | 否 |
| 可脚本化 | 是 |