1# Display<a name="EN-US_TOPIC_0000001124650033"></a> 2 3- [Introduction](#section11660541593) 4- [Directory Structure](#section161941989596) 5 - [Available APIs](#section1551164914237) 6 - [Usage](#section129654513264) 7 8- [Repositories Involved](#section1371113476307) 9 10## Introduction<a name="section11660541593"></a> 11 12This repository defines and implements the following Hardware Driver Interfaces \(HDIs\) of the display module. The HDIs are classified into the following types: 13 14- DisplayLayer: manages display layers, including creating layers, setting display attributes, and filling and flushing layers. 15- DisplayGralloc: manages memory of the display module, including memory application, release, and mapping. 16- DisplayGfx: implements hardware acceleration, including the initialization of the hardware acceleration module, bit blit, and regular graphics drawing and filling. 17 18**Figure 1** HDI architecture of the display module<a name="fig7690246193216"></a> 19 20 21## Directory Structure<a name="section161941989596"></a> 22 23The source code directory structure is as follows: 24 25``` 26/drivers/peripheral/display 27├── hal # HAL code 28│ └── default # Default HDI implementation 29├── interfaces # Driver capability APIs provided for upper-layer services 30│ └── include # APIs exposed externally 31├── test # Test code 32│ └── unittest # Unit test code 33``` 34 35### Available APIs<a name="section1551164914237"></a> 36 37The display driver provides the Window Manager Service \(WMS\) with driver capability APIs that can be classified into the **DisplayLayer**, **DisplayGralloc**, and **DisplayGfx** types. By calling these APIs, you can create or destroy a layer, set layer attributes, allocate, release, map, and buffer memory, fill in rectangles, and blit bitmaps. 38 39[Table 1](#table1513255710559) describes major HDIs provided by the display module. 40 41**Table 1** Major HDIs of the display module 42 43<a name="table1513255710559"></a> 44<table><thead align="left"><tr id="row171321857155517"><th class="cellrowborder" align="center" valign="top" width="12.121212121212123%" id="mcps1.2.4.1.1"><p id="p6132957115511"><a name="p6132957115511"></a><a name="p6132957115511"></a>Header File</p> 45</th> 46<th class="cellrowborder" align="center" valign="top" width="64.95649564956496%" id="mcps1.2.4.1.2"><p id="p14132125715552"><a name="p14132125715552"></a><a name="p14132125715552"></a>API</p> 47</th> 48<th class="cellrowborder" align="center" valign="top" width="22.922292229222922%" id="mcps1.2.4.1.3"><p id="p18132205755516"><a name="p18132205755516"></a><a name="p18132205755516"></a>Description</p> 49</th> 50</tr> 51</thead> 52<tbody><tr id="row13132357165514"><td class="cellrowborder" rowspan="9" valign="top" width="12.121212121212123%" headers="mcps1.2.4.1.1 "><p id="p829618389386"><a name="p829618389386"></a><a name="p829618389386"></a></p> 53<p id="p35261387384"><a name="p35261387384"></a><a name="p35261387384"></a></p> 54<p id="p776383812388"><a name="p776383812388"></a><a name="p776383812388"></a></p> 55<p id="p11950123812382"><a name="p11950123812382"></a><a name="p11950123812382"></a></p> 56<p id="p13168103915381"><a name="p13168103915381"></a><a name="p13168103915381"></a></p> 57<p id="p825185015460"><a name="p825185015460"></a><a name="p825185015460"></a>display_layer.h</p> 58<p id="p2133757135510"><a name="p2133757135510"></a><a name="p2133757135510"></a></p> 59<p id="p1476175815372"><a name="p1476175815372"></a><a name="p1476175815372"></a></p> 60</td> 61<td class="cellrowborder" valign="top" width="64.95649564956496%" headers="mcps1.2.4.1.2 "><p id="p1365411515117"><a name="p1365411515117"></a><a name="p1365411515117"></a>int32_t (*InitDisplay)(uint32_t devId);</p> 62</td> 63<td class="cellrowborder" align="center" valign="top" width="22.922292229222922%" headers="mcps1.2.4.1.3 "><p id="p041814588404"><a name="p041814588404"></a><a name="p041814588404"></a>Initializes the layer.</p> 64</td> 65</tr> 66<tr id="row9132135715515"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1398804043612"><a name="p1398804043612"></a><a name="p1398804043612"></a>int32_t (*DeinitDisplay)(uint32_t devId);</p> 67</td> 68<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p1341845816404"><a name="p1341845816404"></a><a name="p1341845816404"></a>Deinitializes the layer.</p> 69</td> 70</tr> 71<tr id="row171330575555"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1974125024812"><a name="p1974125024812"></a><a name="p1974125024812"></a>int32_t (*GetDisplayInfo)(uint32_t devId, DisplayInfo *dispInfo);</p> 72</td> 73<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p1041815816403"><a name="p1041815816403"></a><a name="p1041815816403"></a>Obtains the display device information.</p> 74</td> 75</tr> 76<tr id="row576145883720"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p8761658183714"><a name="p8761658183714"></a><a name="p8761658183714"></a>int32_t (*OpenLayer)(uint32_t devId, const LayerInfo *layerInfo, uint32_t *layerId);</p> 77</td> 78<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p15418165812409"><a name="p15418165812409"></a><a name="p15418165812409"></a>Creates a layer.</p> 79</td> 80</tr> 81<tr id="row1957862120383"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p55781217381"><a name="p55781217381"></a><a name="p55781217381"></a>int32_t (*CloseLayer)(uint32_t devId, uint32_t layerId);</p> 82</td> 83<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p1641875834010"><a name="p1641875834010"></a><a name="p1641875834010"></a>Destroys a layer.</p> 84</td> 85</tr> 86<tr id="row127635162380"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p3763916143816"><a name="p3763916143816"></a><a name="p3763916143816"></a>int32_t (*SetLayerVisible)(uint32_t devId, uint32_t layerId, bool visible);</p> 87</td> 88<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p10418195874019"><a name="p10418195874019"></a><a name="p10418195874019"></a>Sets whether a layer is visible.</p> 89</td> 90</tr> 91<tr id="row14230131383819"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1723081310386"><a name="p1723081310386"></a><a name="p1723081310386"></a>int32_t (*SetLayerDirtyRegion)(uint32_t devId, uint32_t layerId, IRect *region);</p> 92</td> 93<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p10418658184012"><a name="p10418658184012"></a><a name="p10418658184012"></a>Sets the flushing area for a layer.</p> 94</td> 95</tr> 96<tr id="row159636983816"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p89635916383"><a name="p89635916383"></a><a name="p89635916383"></a>int32_t (*Flush)(uint32_t devId, uint32_t layerId, LayerBuffer *buffer);</p> 97</td> 98<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p19418205894012"><a name="p19418205894012"></a><a name="p19418205894012"></a>Flushes a layer.</p> 99</td> 100</tr> 101<tr id="row76872047153720"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1368818472376"><a name="p1368818472376"></a><a name="p1368818472376"></a>int32_t (*GetLayerBuffer)(uint32_t devId, uint32_t layerId, LayerBuffer *buffer);</p> 102</td> 103<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p144182582405"><a name="p144182582405"></a><a name="p144182582405"></a>Obtains the buffer of a layer.</p> 104</td> 105</tr> 106<tr id="row1513316577554"><td class="cellrowborder" rowspan="7" valign="top" width="12.121212121212123%" headers="mcps1.2.4.1.1 "><p id="p14171441118"><a name="p14171441118"></a><a name="p14171441118"></a></p> 107<p id="p154814318410"><a name="p154814318410"></a><a name="p154814318410"></a></p> 108<p id="p3481154311418"><a name="p3481154311418"></a><a name="p3481154311418"></a></p> 109<p id="p57063567463"><a name="p57063567463"></a><a name="p57063567463"></a>display_gralloc.h</p> 110<p id="p7909447418"><a name="p7909447418"></a><a name="p7909447418"></a></p> 111</td> 112<td class="cellrowborder" valign="top" width="64.95649564956496%" headers="mcps1.2.4.1.2 "><p id="p228510326414"><a name="p228510326414"></a><a name="p228510326414"></a>int32_t AllocMem(GrallocBuffer *buffer);</p> 113</td> 114<td class="cellrowborder" align="center" valign="top" width="22.922292229222922%" headers="mcps1.2.4.1.3 "><p id="p17421321134612"><a name="p17421321134612"></a><a name="p17421321134612"></a>Allocates memory.</p> 115</td> 116</tr> 117<tr id="row171331657185514"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p12841932114117"><a name="p12841932114117"></a><a name="p12841932114117"></a>void FreeMem(GrallocBuffer *buffer);</p> 118</td> 119<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p1874202174615"><a name="p1874202174615"></a><a name="p1874202174615"></a>Releases memory.</p> 120</td> 121</tr> 122<tr id="row41331557165518"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p92831132184119"><a name="p92831132184119"></a><a name="p92831132184119"></a>void *Mmap(GrallocBuffer *buffer);</p> 123</td> 124<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p474262184610"><a name="p474262184610"></a><a name="p474262184610"></a>Maps memory.</p> 125</td> 126</tr> 127<tr id="row77021769584"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p8283123284110"><a name="p8283123284110"></a><a name="p8283123284110"></a>void *MmapCache(GrallocBuffer *buffer);</p> 128</td> 129<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p107422021204615"><a name="p107422021204615"></a><a name="p107422021204615"></a>Maps memory to memory with cache.</p> 130</td> 131</tr> 132<tr id="row71857914585"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p4282032114118"><a name="p4282032114118"></a><a name="p4282032114118"></a>int32_t Unmap(GrallocBuffer *buffer);</p> 133</td> 134<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p374210219468"><a name="p374210219468"></a><a name="p374210219468"></a>Unmaps memory.</p> 135</td> 136</tr> 137<tr id="row884115357415"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p68421035114115"><a name="p68421035114115"></a><a name="p68421035114115"></a>int32_t FlushCache(GrallocBuffer *buffer);</p> 138</td> 139<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1674212113467"><a name="p1674212113467"></a><a name="p1674212113467"></a>Flushes data from the cache to memory and invalidates the data in the cache.</p> 140</td> 141</tr> 142<tr id="row18831119115815"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p172641732134117"><a name="p172641732134117"></a><a name="p172641732134117"></a>int32_t FlushMCache(GrallocBuffer *buffer);</p> 143</td> 144<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p10742182114462"><a name="p10742182114462"></a><a name="p10742182114462"></a>Flushes data from the cache via Mmap to memory and invalidates the data in the cache.</p> 145</td> 146</tr> 147<tr id="row1452521025813"><td class="cellrowborder" rowspan="4" valign="top" width="12.121212121212123%" headers="mcps1.2.4.1.1 "><p id="p033128174618"><a name="p033128174618"></a><a name="p033128174618"></a></p> 148<p id="p4252162854616"><a name="p4252162854616"></a><a name="p4252162854616"></a></p> 149<p id="p10421192894615"><a name="p10421192894615"></a><a name="p10421192894615"></a></p> 150<p id="p12525910165811"><a name="p12525910165811"></a><a name="p12525910165811"></a>display_gfx.h</p> 151</td> 152<td class="cellrowborder" valign="top" width="64.95649564956496%" headers="mcps1.2.4.1.2 "><p id="p16761419154811"><a name="p16761419154811"></a><a name="p16761419154811"></a>int32_t InitGfx(void);</p> 153</td> 154<td class="cellrowborder" align="center" valign="top" width="22.922292229222922%" headers="mcps1.2.4.1.3 "><p id="p1675964994818"><a name="p1675964994818"></a><a name="p1675964994818"></a>Initializes hardware acceleration.</p> 155</td> 156</tr> 157<tr id="row172902161193"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1249042564815"><a name="p1249042564815"></a><a name="p1249042564815"></a>int32_t DeinitGfx(void);</p> 158</td> 159<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p17591149104819"><a name="p17591149104819"></a><a name="p17591149104819"></a>Deinitializes hardware acceleration.</p> 160</td> 161</tr> 162<tr id="row1948179195"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p5783143154816"><a name="p5783143154816"></a><a name="p5783143154816"></a>int32_t Blit(ISurface *srcSurface, IRect *srcRect, ISurface *dstSurface, IRect *dstRect);</p> 163</td> 164<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p1759749134818"><a name="p1759749134818"></a><a name="p1759749134818"></a>Blits bitmaps.</p> 165</td> 166</tr> 167<tr id="row1331121813197"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p2728173711481"><a name="p2728173711481"></a><a name="p2728173711481"></a>int32_t FillRect(ISurface *surface, IRect *rect, uint32_t color, GfxOpt *opt);</p> 168</td> 169<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p107591749104810"><a name="p107591749104810"></a><a name="p107591749104810"></a>Fills a rectangle with a given color on the canvas.</p> 170</td> 171</tr> 172</tbody> 173</table> 174 175### Usage<a name="section129654513264"></a> 176 177The core function of this repository is to provide HDIs for upper-layer display system services to implement display driver capabilities. 178 179The following sample code describes how to use the display HDIs: 180 181``` 182#include "display_gfx.h" 183#include "display_gralloc.h" 184#include "display_layer.h" 185#include "display_type.h" 186 187#define DEVID 0 188DisplayTest g_displayTest; 189static GrallocBuffer g_buffer; 190 191static int32_t GetDisplayInterfaces(void) 192{ 193 int32_t ret; 194 ret = LayerInitialize(&g_displayTest.layerFuncs); 195 if (ret != DISPLAY_SUCCESS || g_displayTest.layerFuncs == NULL) { 196 HDF_LOGE("initialize layer failed"); 197 return DISPLAY_FAILURE; 198 } 199 ret = GrallocInitialize(&g_displayTest.grallocFuncs); 200 if (ret != DISPLAY_SUCCESS || g_displayTest.layerFuncs == NULL) { 201 HDF_LOGE("initialize gralloc failed"); 202 return DISPLAY_FAILURE; 203 } 204 ret = GfxInitialize(&g_displayTest.gfxFuncs); 205 if (ret != DISPLAY_SUCCESS || g_displayTest.gfxFuncs == NULL) { 206 HDF_LOGE("initialize gralloc failed"); 207 return DISPLAY_FAILURE; 208 } 209 return DISPLAY_SUCCESS; 210} 211 212static int32_t DisplayUninit(void) 213{ 214 LayerUninitialize(g_displayTest.layerFuncs); 215 GrallocUninitialize(g_displayTest.grallocFuncs); 216 GfxUninitialize(g_displayTest.gfxFuncs); 217 return DISPLAY_SUCCESS; 218} 219 220static void GetLayerInfo(LayerInfo *layInfo) 221{ 222 layInfo->width = g_displayTest.displayInfo.width; 223 layInfo->height = g_displayTest.displayInfo.height; 224 layInfo->bpp = LAYER_BPP; 225 layInfo->pixFormat = PIXEL_FMT_RGBA_5551; 226 layInfo->type = LAYER_TYPE_GRAPHIC; 227} 228 229static void WriteDataToBuf(int32_t width, int32_t height, uint16_t *pBuf) 230{ 231 int32_t x; 232 int32_t y; 233 234 for (y = ((height / LINE_WIDTH) - LINE_WIDTH); y < ((height / LINE_WIDTH) + LINE_WIDTH); y++) { 235 for (x = 0; x < width; x++) { 236 *((uint16_t*)pBuf + y * width + x) = HIFB_RED_1555; 237 } 238 } 239 for (y = 0; y < height; y++) { 240 for (x = ((width / LINE_WIDTH) - LINE_WIDTH); x < ((width / LINE_WIDTH) + LINE_WIDTH); x++) { 241 *((uint16_t*)pBuf + y * width + x) = HIFB_RED_1555; 242 } 243 } 244} 245 246int DisplayServiceSample(void) 247{ 248 int32_t ret; 249 g_displayTest.devId = DEVID; 250 251 /* Obtain display driver APIs. */ 252 ret = GetDisplayInterfaces(); 253 if (ret != DISPLAY_SUCCESS) { 254 HDF_LOGE("get display interfaces ops failed"); 255 return ret; 256 } 257 /* Initialize a display device. */ 258 if (g_displayTest.layerFuncs->InitDisplay != NULL) { 259 ret = g_displayTest.layerFuncs->InitDisplay(g_displayTest.devId); 260 if (ret != DISPLAY_SUCCESS) { 261 HDF_LOGE("initialize display failed"); 262 return DISPLAY_FAILURE; 263 } 264 } 265 /* Obtain the display device information. */ 266 if (g_displayTest.layerFuncs->GetDisplayInfo != NULL) { 267 ret = g_displayTest.layerFuncs->GetDisplayInfo(g_displayTest.devId, &g_displayTest.displayInfo); 268 if (ret != DISPLAY_SUCCESS) { 269 HDF_LOGE("get disp info failed"); 270 return DISPLAY_FAILURE; 271 } 272 } 273 /* Open a specific layer of the display device. */ 274 if (g_displayTest.layerFuncs->OpenLayer != NULL) { 275 LayerInfo layInfo; 276 GetLayerInfo(&layInfo); 277 ret = g_displayTest.layerFuncs->OpenLayer(g_displayTest.devId, &layInfo, &g_displayTest.layerId); 278 if (ret != DISPLAY_SUCCESS) { 279 HDF_LOGE("open layer failed"); 280 return DISPLAY_FAILURE; 281 } 282 } 283 /* Obtain the buffer of the layer and add data to the buffer. */ 284 if (g_displayTest.layerFuncs->GetLayerBuffer != NULL) { 285 ret = g_displayTest.layerFuncs->GetLayerBuffer(g_displayTest.devId, g_displayTest.layerId, &g_displayTest.buffer); 286 if (ret != DISPLAY_SUCCESS) { 287 HDF_LOGE("get layer buffer failed"); 288 return DISPLAY_FAILURE; 289 } 290 uint16_t *pBuf = (uint16_t *)g_displayTest.buffer.data.virAddr; 291 WriteDataToBuf(g_displayTest.displayInfo.width, g_displayTest.displayInfo.height, pBuf); 292 } 293 /* Flush the layer data for display. */ 294 if (g_displayTest.layerFuncs->Flush != NULL) { 295 ret = g_displayTest.layerFuncs->Flush(g_displayTest.devId, g_displayTest.layerId, &g_displayTest.buffer); 296 if (ret != DISPLAY_SUCCESS) { 297 HDF_LOGE("flush layer failed"); 298 return DISPLAY_FAILURE; 299 } 300 } 301 /* Close the specified layer of the display device. */ 302 if (g_displayTest.layerFuncs->CloseLayer != NULL) { 303 ret = g_displayTest.layerFuncs->CloseLayer(g_displayTest.devId, g_displayTest.layerId); 304 if (ret != DISPLAY_SUCCESS) { 305 HDF_LOGE("close layer failed"); 306 return DISPLAY_FAILURE; 307 } 308 } 309 /* Close the display device. */ 310 if (g_displayTest.layerFuncs->DeinitDisplay != NULL) { 311 ret = g_displayTest.layerFuncs->DeinitDisplay(g_displayTest.devId); 312 if (ret != DISPLAY_SUCCESS) { 313 HDF_LOGE("deinit display failed"); 314 return DISPLAY_FAILURE; 315 } 316 } 317 /* Unregister display driver APIs. */ 318 ret = DisplayUninit(); 319 if (ret != DISPLAY_SUCCESS) { 320 HDF_LOGE("DisplayUninit fail"); 321 return ret; 322 } 323 return 0; 324} 325``` 326 327## Repositories Involved<a name="section1371113476307"></a> 328 329[Driver subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/driver-subsystem.md) 330 331[drivers\_framework](https://gitee.com/openharmony/drivers_framework/blob/master/README.md) 332 333[drivers\_adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README.md) 334 335[drivers\_adapter\_khdf\_linux](https://gitee.com/openharmony/drivers_adapter_khdf_linux/blob/master/README.md) 336 337[drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral) 338 339
