1# drawing_surface.h 2 3## 概述 4 5文件中定义与surface相关的功能函数，包括surface的创建、销毁和使用等。 6 7**引用文件：** <native_drawing/drawing_surface.h> 8 9**库：** libnative_drawing.so 10 11**起始版本：** 12 12 13**相关模块：** [Drawing](capi-drawing.md) 14 15## 汇总 16 17### 函数 18 19| 名称 | 描述 | 20| -- | -- | 21| [OH_Drawing_Surface* OH_Drawing_SurfaceCreateFromGpuContext(OH_Drawing_GpuContext* gpuContext, bool flag, OH_Drawing_Image_Info imageInfo)](#oh_drawing_surfacecreatefromgpucontext) | 使用图形处理器上下文创建一个surface对象，用于管理画布绘制的内容。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>gpuContext为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 22| [OH_Drawing_Surface* OH_Drawing_SurfaceCreateOnScreen(OH_Drawing_GpuContext* gpuContext, OH_Drawing_Image_Info imageInfo, void* window)](#oh_drawing_surfacecreateonscreen) | 使用图形处理器上下文创建一个与屏幕窗口绑定的surface对象，用于管理画布绘制的内容。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>gpuContext或window为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 23| [OH_Drawing_Canvas* OH_Drawing_SurfaceGetCanvas(OH_Drawing_Surface* surface)](#oh_drawing_surfacegetcanvas) | 通过surface对象获取画布对象。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>surface为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 | 24| [OH_Drawing_ErrorCode OH_Drawing_SurfaceFlush(OH_Drawing_Surface* surface)](#oh_drawing_surfaceflush) | 将surface对象上的画布绘制内容提交给GPU处理，完成绘制内容上屏显示。 | 25| [void OH_Drawing_SurfaceDestroy(OH_Drawing_Surface* surface)](#oh_drawing_surfacedestroy) | 销毁surface对象并回收该对象占用的内存。 | 26 27## 函数说明 28 29### OH_Drawing_SurfaceCreateFromGpuContext() 30 31``` 32OH_Drawing_Surface* OH_Drawing_SurfaceCreateFromGpuContext(OH_Drawing_GpuContext* gpuContext, bool flag, OH_Drawing_Image_Info imageInfo) 33``` 34 35**描述** 36 37使用图形处理器上下文创建一个surface对象，用于管理画布绘制的内容。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>gpuContext为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 38 39**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 40 41**起始版本：** 12 42 43 44**参数：** 45 46| 参数项 | 描述 | 47| -- | -- | 48| [OH_Drawing_GpuContext](capi-drawing-oh-drawing-gpucontext.md)* gpuContext | 指向图形处理器上下文对象的指针[OH_Drawing_GpuContext](capi-drawing-oh-drawing-gpucontext.md)。 | 49| bool flag | 用于控制内存分配是否计入缓存预算。true则计入高速缓存预算，false则不计入高速缓存预算。 | 50| [OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md) imageInfo | 图片信息[OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md)结构体。 | 51 52**返回：** 53 54| 类型 | 说明 | 55| -- | -- | 56| [OH_Drawing_Surface](capi-drawing-oh-drawing-surface.md)* | 返回一个指针，指针指向创建的surface对象[OH_Drawing_Surface](capi-drawing-oh-drawing-surface.md)。 | 57 58### OH_Drawing_SurfaceCreateOnScreen() 59 60``` 61OH_Drawing_Surface* OH_Drawing_SurfaceCreateOnScreen(OH_Drawing_GpuContext* gpuContext, OH_Drawing_Image_Info imageInfo, void* window) 62``` 63 64**描述** 65 66使用图形处理器上下文创建一个与屏幕窗口绑定的surface对象，用于管理画布绘制的内容。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>gpuContext或window为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 67 68**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 69 70**起始版本：** 16 71 72 73**参数：** 74 75| 参数项 | 描述 | 76| -- | -- | 77| [OH_Drawing_GpuContext](capi-drawing-oh-drawing-gpucontext.md)* gpuContext | 指向图形处理器上下文对象的指针[OH_Drawing_GpuContext](capi-drawing-oh-drawing-gpucontext.md)。<br>该图形处理器上下文对象必须由[OH_Drawing_GpuContextCreate](capi-drawing-gpu-context-h.md#oh_drawing_gpucontextcreate)创建，否则surface对象会创建失败。 | 78| [OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md) imageInfo | 图片信息[OH_Drawing_Image_Info](capi-drawing-oh-drawing-image-info.md)结构体。 | 79| void* window | 指向屏幕窗口对象的指针。 | 80 81**返回：** 82 83| 类型 | 说明 | 84| -- | -- | 85| [OH_Drawing_Surface](capi-drawing-oh-drawing-surface.md)* | 返回一个指针，指针指向创建的surface对象[OH_Drawing_Surface](capi-drawing-oh-drawing-surface.md)。 | 86 87### OH_Drawing_SurfaceGetCanvas() 88 89``` 90OH_Drawing_Canvas* OH_Drawing_SurfaceGetCanvas(OH_Drawing_Surface* surface) 91``` 92 93**描述** 94 95通过surface对象获取画布对象。<br>本接口会产生错误码，可以通过[OH_Drawing_ErrorCodeGet](capi-drawing-error-code-h.md#oh_drawing_errorcodeget)查看错误码的取值。<br>surface为NULL时返回OH_DRAWING_ERROR_INVALID_PARAMETER。 96 97**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 98 99**起始版本：** 12 100 101 102**参数：** 103 104| 参数项 | 描述 | 105| -- | -- | 106| [OH_Drawing_Surface](capi-drawing-oh-drawing-surface.md)* surface | 指向创建的surface对象的指针。 | 107 108**返回：** 109 110| 类型 | 说明 | 111| -- | -- | 112| [OH_Drawing_Canvas](capi-drawing-oh-drawing-canvas.md)* | 返回一个指针，指针指向创建的画布对象[OH_Drawing_Canvas](capi-drawing-oh-drawing-canvas.md)。返回的指针不需要由调用者管理。 | 113 114### OH_Drawing_SurfaceFlush() 115 116``` 117OH_Drawing_ErrorCode OH_Drawing_SurfaceFlush(OH_Drawing_Surface* surface) 118``` 119 120**描述** 121 122将surface对象上的画布绘制内容提交给GPU处理，完成绘制内容上屏显示。 123 124**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 125 126**起始版本：** 16 127 128 129**参数：** 130 131| 参数项 | 描述 | 132| -- | -- | 133| [OH_Drawing_Surface](capi-drawing-oh-drawing-surface.md)* surface | 指向创建的surface对象的指针[OH_Drawing_Surface](capi-drawing-oh-drawing-surface.md)。该surface对象必须由[OH_Drawing_SurfaceCreateOnScreen](capi-drawing-surface-h.md#oh_drawing_surfacecreateonscreen)创建，否则该接口调用将没有任何效果。 | 134 135**返回：** 136 137| 类型 | 说明 | 138| -- | -- | 139| [OH_Drawing_ErrorCode](capi-drawing-error-code-h.md#oh_drawing_errorcode) | 函数返回执行错误码。<br> 返回OH_DRAWING_SUCCESS，表示执行成功。<br> 返回OH_DRAWING_ERROR_INVALID_PARAMETER，表示参数surface为空。 | 140 141### OH_Drawing_SurfaceDestroy() 142 143``` 144void OH_Drawing_SurfaceDestroy(OH_Drawing_Surface* surface) 145``` 146 147**描述** 148 149销毁surface对象并回收该对象占用的内存。 150 151**系统能力：** SystemCapability.Graphic.Graphic2D.NativeDrawing 152 153**起始版本：** 12 154 155 156**参数：** 157 158| 参数项 | 描述 | 159| -- | -- | 160| [OH_Drawing_Surface](capi-drawing-oh-drawing-surface.md)* surface | 指向创建的surface对象的指针。 | 161 162 163