黑暗模式
如何使用离线的 canvas
canvas 在 awtk 中是画布的意思，而且用户常常是通过回调函数回去是在线 canvas 来进行绘图，但是在在线 canvas 上面画东西就会显示到屏幕上面。
为了解决用户离线画布的需求，所以 awtk 中提供了 canvas_offline_xxx 系列函数给用户使用。
一，创建离线画布 canvas
下面为创建离线画布 canvas 的函数，在离线画布 canvas 内置了一个离线的 bitmap，提供给用户使用。
c
/**
* @method canvas_offline_create
* 创建一个离线的 canvas
* 在 opengl 模式下 format 参数只能为 BITMAP_FMT_RGBA8888
* 在其他模式下，离线 canvas 格式可以为 rgba，bgar，bgr565和rgb565
*
* @param {uint32_t} w 离线 canvas 的宽。
* @param {uint32_t} h 离线 canvas 的高。
* @param {bitmap_format_t} format 离线 canvas 的格式。
*
* @return {canvas_t*} 成功返回 canvas ，失败返回 NULL。
*/
canvas_t* canvas_offline_create(uint32_t w, uint32_t h, bitmap_format_t format);
/**
* @method canvas_offline_get_bitmap
* 获取离线 canvas 的离线 bitmap。
*
* @param {canvas_t*} canvas 离线 canvas 对象。
*
* @return {bitmap_t*} 返回 bitmap_t 对象表示成功，返回 NULL 表示失败。
*/
bitmap_t* canvas_offline_get_bitmap(canvas_t* canvas);下面代码，创建离线 canvas：
c
static canvas_t* canvas_offline = NULL;
/* 创建离线的 canvas */
canvas_offline = canvas_offline_create(320, 480, BITMAP_FMT_RGBA8888);备注：在 opengl 模式下离线 canvas 格式只能为 RGBA8888，而在 AGGE 下可以为 RGBA8888，BGRA8888，RGB565 和 BGR5656。（其他的格式暂时不支持）
二，绘图离线画布 canvas
离线 canvas 的绘图过程和平时使用 canvas 绘图是一样的，只不过在绘制之前需要先调用 canvas_offline_begin_draw 函数，结束的时候调用 canvas_offline_end_draw 函数。
c
/**
* @method canvas_offline_clear_canvas
* 把离线 canvas 清除所有数据，并把背景设置为全透明（注意：该离线 canvas 需要有透明通道）
* 该函数调用前必须要先 canvas_offline_begin_draw 函数。
* 该函数用来解决离线 canvas 多次绘图半透效果后导致半透效果无效的问题。
*
* @param {canvas_t*} canvas 离线 canvas 对象。
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t canvas_offline_clear_canvas(canvas_t* canvas);
/**
* @method canvas_offline_bitmap_move_to_new_bitmap
* 把离线 canvas 的离线 bitmap 移动赋值给新的 bitmap。
* 移动赋值后原来的离线 canvas 的离线 bitmap 就会被置空。
* 备注：在移动赋值之前会先调用 canvas_offline_flush_bitmap 把数据回流到内存中。
*
* @param {canvas_t*} canvas 离线 canvas 对象。
*
* @return {bitmap_t*} 返回 bitmap_t 对象表示成功，返回 NULL 表示失败。
*/
ret_t canvas_offline_bitmap_move_to_new_bitmap(canvas_t* canvas, bitmap_t* bitmap);
/**
* @method canvas_offline_flush_bitmap
* 把离线 canvas 的数据放到绑定的 bitmap 中
* 该函数只有在 opengl 模式才需要调用，是否把显存中的数据回传到内存中。
*
* @param {canvas_t*} canvas 离线 canvas 对象。
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t canvas_offline_flush_bitmap(canvas_t* canvas);下面代码把整个窗口绘制到离线 canvas 上面。
c
bitmap_t* offline_bitmap = NULL;
/* 开始离线 canvas 绘图 */
canvas_begin_frame(canvas_offline);
/* 把整个窗口绘制到离线的 canvas 中 */
widget_paint(window_manager(), canvas_offline);
/* 结束离线 canvas 绘图 */
canvas_end_frame(canvas_offline);
/* 由于需要把 bitmap 保存为 png 文件，所以需要把显存中的数据回传到内存中 */
canvas_offline_flush_bitmap(canvas_offline);
/* 获取离线的 canvas 对应的离线 bitmap */
offline_bitmap = canvas_offline_get_bitmap(canvas_offline);
/* 把 bitmap 保存到 png 文件 */
bitmap_save_png(offline_bitmap, "test.png");备注：
- 如果 awtk 在 opengl 模式下，同时需要操作 bitmap 中的位图数据的话，就需要调用 canvas_offline_flush_bitmap 函数把 GPU 中的显存数据回传到内存中。
- canvas 的所有函数，离线 canvas 都可以调用，并且绘制数据只会放到离线 canvas 中。
- 如果需要使用 vg 的话，可以通过 canvas_get_vgcanvas 函数，获取离线 canvas 的 vg 对象。
三，释放离线画布 canvas
释放离线画布只是释放对应的离线 canvas，而不会释放绑定的 bitmap，bitmap 需要用户自行管理。
c
/**
* @method canvas_offline_destroy
* 释放离线 canvas 和离线 bitmap
*
* @param {canvas_t*} canvas 离线 canvas 对象。
*
* @return {ret_t} 返回RET_OK表示成功，否则表示失败。
*/
ret_t canvas_offline_destroy(canvas_t* canvas);四，用户自定义特殊的离线画布 canvas
由于有一些特别平台不能直接使用 awtk 提供的离线 canvas，只能通过平台的一些特殊的接口来实现离线画布 canvas，所以 awtk 的离线 canvas 提供了一个给外部重载离线 canvas 的函数的方法。
通过定义 WITH_CANVAS_OFFLINE_CUSTOM 宏，并且用户自行重写下面的函数，并且返回值必须是 RET_OK 或者非 NULL：
| 函数名字 | 作用 |
|---|---|
| canvas_offline_custom_create | 用户自定义 canvas_offline_create |
| canvas_offline_custom_clear_canvas | 用户自定义 canvas_offline_custom_clear_canvas |
| canvas_offline_custom_begin_draw | 用户自定义 canvas_offline_custom_begin_draw |
| canvas_offline_custom_end_draw | 用户自定义 canvas_offline_custom_end_draw |
| canvas_offline_custom_get_bitmap | 用户自定义 canvas_offline_custom_get_bitmap |
| canvas_offline_custom_bitmap_move_to_new_bitmap | 用户自定义 canvas_offline_custom_bitmap_move_to_new_bitmap |
| canvas_offline_custom_flush_bitmap | 用户自定义 canvas_offline_custom_flush_bitmap |
| canvas_offline_custom_destroy | 用户自定义 canvas_offline_custom_destroy |
备注：如果用户只需要部分函数的实现的话，可以把其他的函数返回 RET_FAIL 或者 NULL ，即可以让离线画布 canvas 函数执行回 awtk 的原来的代码逻辑。
具体用法请参考 demo_offline_canvas.c