1# Display VDI
2
3## Overview
4The display vendor device interface (VDI) is provided for chip vendor devices to access to the OpenHarmony display driver framework model.
5The display VDI interface consists of the following:
6
7- Composer: implements layer composition and display.
8- Buffer: implements allocation and release of the surface buffer.
9
10### Composer
11
12**Figure 1** Display composer HDI architecture
13
14![](figures/Display_Composer_HDI_architecture.png)
15
16The framework model consists of the following layers:
17
18+ Framework layer: interacts with the HDI implementation layer to implements composition and display of layers and manages hardware devices of the display module.
19+ HDI implementation layer: implements the OpenHarmony Composer HDI interface.
20+ Vendor driver layer: supports multi-platform adaptation by shielding the differences between underlying chips and OSs.
21
22### Buffer
23
24**Figure 2** Display buffer HDI architecture
25
26![](figures/Display_Buffer_HDI_architecture.png)
27
28The framework model consists of the following layers:
29
30+ Framework layer: interacts with the HDI implementation layer to implements allocation and release of graphics buffers.
31+ HDI implementation layer: implements the OpenHarmony buffer HDI interface.
32+ Vendor driver layer: supports multi-platform adaptation by shielding the differences between underlying chips and OSs.
33
34
35## Development Guidelines
36
37### Composer
38
39#### Available APIs
40
41You can obtain the VDI declaration file **/drivers/peripheral/display/composer/hdi_service/include/idisplay_composer_vdi.h** from [https://gitee.com/openharmony/drivers_peripheral/tree/master/display/composer](https://gitee.com/openharmony/drivers_peripheral/tree/master/display/composer).
42- idisplay_composer_vdi.h
43
44  | API                                                    | Description                                         |
45  | ------------------------------------------------------------ | ------------------------------------------------------------ |
46  | int32_t RegHotPlugCallback(HotPlugCallback cb, void* data) | Registers a callback for a hot plug event. |
47  | int32_t GetDisplayCapability(uint32_t devId, DisplayCapability& info) | Obtains the capability set of a display device. |
48  | int32_t GetDisplaySupportedModes(uint32_t devId, std::vector\<DisplayModeInfo\>& modes) | Obtains the supported display modes of a display device. |
49  | int32_t GetDisplayMode(uint32_t devId, uint32_t& modeId) | Obtains the current display mode of a display device. |
50  | int32_t SetDisplayMode(uint32_t devId, uint32_t modeId) | Sets the display mode of a display device. |
51  | int32_t GetDisplayPowerStatus(uint32_t devId, DispPowerStatus& status) | Obtains the power status of a display device. |
52  | int32_t SetDisplayPowerStatus(uint32_t devId, DispPowerStatus status) | Sets the power status of a display device. |
53  | int32_t GetDisplayBacklight(uint32_t devId, uint32_t& level) | Obtains the backlight value of a display device. |
54  | int32_t SetDisplayBacklight(uint32_t devId, uint32_t level) | Sets the backlight value for a display device. |
55  | int32_t GetDisplayProperty(uint32_t devId, uint32_t id, uint64_t& value) | Obtains a property of a display device. |
56  | int32_t GetDisplayCompChange(uint32_t devId, std::vector\<uint32_t\>& layers, std::vector\<int32_t\>& types) | Obtains the layer whose composition type is changed for a display device. |
57  | int32_t SetDisplayClientCrop(uint32_t devId, const IRect& rect) | Sets the cropping area of a display device. |
58  | int32_t SetDisplayClientBuffer(uint32_t devId, const BufferHandle& buffer, int32_t fence) | Sets the display buffer of the display device. |
59  | int32_t SetDisplayClientDamage(uint32_t devId, std::vector\<IRect\>& rects) | Sets the dirty region of a display device. |
60  | int32_t SetDisplayVsyncEnabled(uint32_t devId, bool enabled) | Enables the vertical sync signal. |
61  | int32_t RegDisplayVBlankCallback(uint32_t devId, VBlankCallback cb, void* data) | Registers a VBlank event callback. |
62  | int32_t GetDisplayReleaseFence(uint32_t devId, std::vector\<uint32_t\>& layers, std::vector\<int32_t\>& fences) | Obtains the display layer fence. |
63  | int32_t CreateVirtualDisplay(uint32_t width, uint32_t height, int32_t& format, uint32_t& devId) | Creates a virtual display device. |
64  | int32_t DestroyVirtualDisplay(uint32_t devId) | Destroys a virtual display device. |
65  | int32_t SetVirtualDisplayBuffer(uint32_t devId, const BufferHandle& buffer, const int32_t fence) | Sets the output buffer of a virtual display. |
66  | int32_t SetDisplayProperty(uint32_t devId, uint32_t id, uint64_t value) | Sets a property for a display device. |
67  | int32_t Commit(uint32_t devId, int32_t& fence) | Commits a composition request. |
68  | int32_t CreateLayer(uint32_t devId, const LayerInfo& layerInfo, uint32_t& layerId) | Creates a layer. |
69  | int32_t DestroyLayer(uint32_t devId, uint32_t layerId) | Destroys a layer. |
70  | int32_t PrepareDisplayLayers(uint32_t devId, bool& needFlushFb) | Prepares the layers to display. |
71  | int32_t SetLayerAlpha(uint32_t devId, uint32_t layerId, const LayerAlpha& alpha) | Sets the alpha value of a layer. |
72  | int32_t SetLayerRegion(uint32_t devId, uint32_t layerId, const IRect& rect) | Sets the region for a layer. |
73  | int32_t SetLayerCrop(uint32_t devId, uint32_t layerId, const IRect& rect) | Sets the cropping area for a layer. |
74  | int32_t SetLayerZorder(uint32_t devId, uint32_t layerId, uint32_t zorder) | Sets the Z-axis order for a layer. |
75  | int32_t SetLayerPreMulti(uint32_t devId, uint32_t layerId, bool preMul) | Sets the premultiplication for a layer. |
76  | int32_t SetLayerTransformMode(uint32_t devId, uint32_t layerId, TransformType type) | Sets the transform mode for a layer. |
77  | int32_t SetLayerDirtyRegion(uint32_t devId, uint32_t layerId, const std::vector\<IRect\>& rects) | Sets the dirty region of a layer. |
78  | int32_t SetLayerVisibleRegion(uint32_t devId, uint32_t layerId, std::vector\<IRect\>& rects) | Sets the visible region of a layer. |
79  | int32_t SetLayerBuffer(uint32_t devId, uint32_t layerId, const BufferHandle& buffer, int32_t fence) | Sets the buffer for a layer. |
80  | int32_t SetLayerCompositionType(uint32_t devId, uint32_t layerId, CompositionType type) | Sets the expected composition type for the client. |
81  | int32_t SetLayerBlendType(uint32_t devId, uint32_t layerId, BlendType type) | Sets the blend type for a layer. |
82  | int32_t SetLayerMaskInfo(uint32_t devId, uint32_t layerId, const MaskInfo maskInfo) | Sets the layer mask information. |
83  | int32_t SetLayerColor(uint32_t devId, uint32_t layerId, const LayerColor& layerColor) | Sets the color for a layer. |
84
85#### How to Develop
86The following walks you through on how to implement the rk3568 composer VDI.
87
881. Implement the composer VDI APIs.
89
90Implement the APIs defined in **idisplay_composer_vdi.h**.
91
92```c++
93  class DisplayComposerVdiImpl : public IDisplayComposerVdi {
94  public:
95      DisplayComposerVdiImpl();
96      virtual ~DisplayComposerVdiImpl();
97      virtual int32_t RegHotPlugCallback(HotPlugCallback cb, void* data) override;
98      virtual int32_t GetDisplayCapability(uint32_t devId, DisplayCapability& info) override;
99      virtual int32_t GetDisplaySupportedModes(uint32_t devId, std::vector<DisplayModeInfo>& modes) override;
100      virtual int32_t GetDisplayMode(uint32_t devId, uint32_t& modeId) override;
101      virtual int32_t SetDisplayMode(uint32_t devId, uint32_t modeId) override;
102      virtual int32_t GetDisplayPowerStatus(uint32_t devId, DispPowerStatus& status) override;
103      virtual int32_t SetDisplayPowerStatus(uint32_t devId, DispPowerStatus status) override;
104      virtual int32_t GetDisplayBacklight(uint32_t devId, uint32_t& level) override;
105      virtual int32_t SetDisplayBacklight(uint32_t devId, uint32_t level) override;
106      virtual int32_t GetDisplayProperty(uint32_t devId, uint32_t id, uint64_t& value) override;
107      virtual int32_t GetDisplayCompChange(uint32_t devId, std::vector<uint32_t>& layers,
108          std::vector<int32_t>& types) override;
109      virtual int32_t SetDisplayClientCrop(uint32_t devId, const IRect& rect) override;
110      virtual int32_t SetDisplayClientBuffer(uint32_t devId, const BufferHandle& buffer, int32_t fence) override;
111      virtual int32_t SetDisplayClientDamage(uint32_t devId, std::vector<IRect>& rects) override;
112      virtual int32_t SetDisplayVsyncEnabled(uint32_t devId, bool enabled) override;
113      virtual int32_t RegDisplayVBlankCallback(uint32_t devId, VBlankCallback cb, void* data) override;
114      virtual int32_t GetDisplayReleaseFence(uint32_t devId, std::vector<uint32_t>& layers,
115          std::vector<int32_t>& fences) override;
116      virtual int32_t CreateVirtualDisplay(uint32_t width, uint32_t height, int32_t& format, uint32_t& devId) override;
117      virtual int32_t DestroyVirtualDisplay(uint32_t devId) override;
118      virtual int32_t SetVirtualDisplayBuffer(uint32_t devId, const BufferHandle& buffer, const int32_t fence) override;
119      virtual int32_t SetDisplayProperty(uint32_t devId, uint32_t id, uint64_t value) override;
120      virtual int32_t Commit(uint32_t devId, int32_t& fence) override;
121      virtual int32_t CreateLayer(uint32_t devId, const LayerInfo& layerInfo, uint32_t& layerId) override;
122      virtual int32_t DestroyLayer(uint32_t devId, uint32_t layerId) override;
123      virtual int32_t PrepareDisplayLayers(uint32_t devId, bool& needFlushFb) override;
124      virtual int32_t SetLayerAlpha(uint32_t devId, uint32_t layerId, const LayerAlpha& alpha) override;
125      virtual int32_t SetLayerRegion(uint32_t devId, uint32_t layerId, const IRect& rect) override;
126      virtual int32_t SetLayerCrop(uint32_t devId, uint32_t layerId, const IRect& rect) override;
127      virtual int32_t SetLayerZorder(uint32_t devId, uint32_t layerId, uint32_t zorder) override;
128      virtual int32_t SetLayerPreMulti(uint32_t devId, uint32_t layerId, bool preMul) override;
129      virtual int32_t SetLayerTransformMode(uint32_t devId, uint32_t layerId, TransformType type) override;
130      virtual int32_t SetLayerDirtyRegion(uint32_t devId, uint32_t layerId, const std::vector<IRect>& rects) override;
131      virtual int32_t SetLayerVisibleRegion(uint32_t devId, uint32_t layerId, std::vector<IRect>& rects) override;
132      virtual int32_t SetLayerBuffer(uint32_t devId, uint32_t layerId,
133          const BufferHandle& buffer, int32_t fence) override;
134      virtual int32_t SetLayerCompositionType(uint32_t devId, uint32_t layerId, CompositionType type) override;
135      virtual int32_t SetLayerBlendType(uint32_t devId, uint32_t layerId, BlendType type) override;
136      virtual int32_t SetLayerMaskInfo(uint32_t devId, uint32_t layerId, const MaskInfo maskInfo) override;
137      virtual int32_t SetLayerColor(uint32_t devId, uint32_t layerId, const LayerColor& layerColor) override;
138  };
139  using CreateComposerVdiFunc = IDisplayComposerVdi* (*)();
140  using DestroyComposerVdiFunc = void (*)(IDisplayComposerVdi* vdi);
141  extern "C" IDisplayComposerVdi* CreateComposerVdi();
142  extern "C" void DestroyComposerVdi(IDisplayComposerVdi* vdi);
143```
144
1452. Build a shared library.
146
147Build a shared library named **libdisplay_composer_vdi_impl.z.so**. Write the **BUILD.gn** file. You can obtain the **BUILD.gn** file of rk3568 from [https://gitee.com/openharmony/device_soc_rockchip/blob/master/rk3568/hardware/display/BUILD.gn](https://gitee.com/openharmony/device_soc_rockchip/blob/master/rk3568/hardware/display/BUILD.gn).
148
149```
150  ohos_shared_library("libdisplay_composer_vdi_impl") {
151    sources = [ "src/display_device/display_composer_vdi_impl.cpp" ]
152
153    include_dirs = [
154      "src/display_device",
155      "${root_path}/drivers/peripheral/display/utils/include",
156      "${root_path}/drivers/interface/display/composer",
157      "${root_path}/drivers/peripheral/display/composer/hdi_service/include",
158      "${root_path}/drivers/interface/display/composer/hdifd_parcelable",
159    ]
160
161    deps = [ ":display_composer_vendor" ]
162
163    external_deps = [
164      "c_utils:utils",
165      "drivers_interface_display:display_composer_idl_headers",
166      "graphic_chipsetsdk:buffer_handle",
167      "hilog:libhilog",
168      "ipc:ipc_single",
169    ]
170
171    install_enable = true
172    install_images = [ chipset_base_dir ]
173    subsystem_name = "hdf"
174    part_name = "rockchip_products"
175  }
176```
177In the root directory of your project, run the following command to build the share library:
178
179```
180  ./build.sh -p rk3568 -T display_composer_model
181```
182Then, you can find **libdisplay_composer_vdi_impl.z.so** in the **out/rk3568/hdf/rockchip_products** directory.
183
184#### Development Example
185
186A default VDI implementation is provided for your reference. For details, see **drivers/peripheral/display/composer/vdi_base** at [https://gitee.com/openharmony/drivers_peripheral/tree/master/display/composer/vdi_base](https://gitee.com/openharmony/drivers_peripheral/tree/master/display/composer/vdi_base).
187
188### Buffer
189
190#### Available APIs
191
192You can obtain the VDI declaration file **/drivers/peripheral/display/buffer/hdi_service/include/idisplay_buffer_vdi.h** from [https://gitee.com/openharmony/drivers_peripheral/tree/master/display/buffer](https://gitee.com/openharmony/drivers_peripheral/tree/master/display/buffer).
193- idisplay_composer_vdi.h
194
195  | API                                                    | Description                                         |
196  | ------------------------------------------------------------ | ------------------------------------------------------------ |
197  | int32_t AllocMem(const AllocInfo& info, BufferHandle*& handle) | Allocates a buffer. |
198  | void FreeMem(const BufferHandle& handle) | Releases a buffer. |
199  | void* Mmap(const BufferHandle& handle) | Maps a buffer to the memory. |
200  | int32_t Unmap(const BufferHandle& handle) | Unmaps a buffer. |
201  | int32_t FlushCache(const BufferHandle& handle) | Flushes a buffer. |
202  | int32_t InvalidateCache(const BufferHandle& handle) | Invalidates a buffer. |
203  | int32_t IsSupportedAlloc(const std::vector<VerifyAllocInfo>& infos, std::vector<bool>& supporteds) | Checks whether the requested buffer can be allocated. |
204  | int32_t RegisterBuffer(const BufferHandle& handle) | Registers a buffer. |
205  | int32_t GetMetadata(const BufferHandle& handle, uint32_t key, std::vector<uint8_t>& value) | Obtains the metadata of a buffer. |
206  | int32_t ListMetadataKeys(const BufferHandle& handle, std::vector<uint32_t>& keys) | Lists the keys of the metadata. |
207  | int32_t EraseMetadataKey(const BufferHandle& handle, uint32_t key) | Erases the metadata of the specified key. |
208
209#### How to Develop
210The following walks you through on how to implement the rk3568 buffer VDI.
211
2121. Implement the buffer VDI APIs.
213
214   Implement the APIs defined in **idisplay_buffer_vdi.h**.
215
216```c++
217  class DisplayBufferVdiImpl : public IDisplayBufferVdi {
218  public:
219      DisplayBufferVdiImpl();
220      virtual ~DisplayBufferVdiImpl();
221
222      virtual int32_t AllocMem(const AllocInfo& info, BufferHandle*& handle) const override;
223      virtual void FreeMem(const BufferHandle& handle) const override;
224      virtual void *Mmap(const BufferHandle& handle) const override;
225      virtual int32_t Unmap(const BufferHandle& handle) const override;
226      virtual int32_t FlushCache(const BufferHandle& handle) const override;
227      virtual int32_t InvalidateCache(const BufferHandle& handle) const override;
228      virtual int32_t IsSupportedAlloc(const std::vector<VerifyAllocInfo>& infos,
229          std::vector<bool>& supporteds) const override;
230      virtual int32_t RegisterBuffer(const BufferHandle& handle) override;
231      virtual int32_t SetMetadata(const BufferHandle& handle, uint32_t key, const std::vector<uint8_t>& value) override;
232      virtual int32_t GetMetadata(const BufferHandle& handle, uint32_t key, std::vector<uint8_t>& value) override;
233      virtual int32_t ListMetadataKeys(const BufferHandle& handle, std::vector<uint32_t>& keys) override;
234      virtual int32_t EraseMetadataKey(const BufferHandle& handle, uint32_t key) override;
235  };
236  using CreateDisplayBufferVdiFunc = IDisplayBufferVdi* (*)();
237  using DestroyDisplayBufferVdiFunc = void (*)(IDisplayBufferVdi* vdi);
238  extern "C" IDisplayBufferVdi* CreateDisplayBufferVdi();
239  extern "C" void DestroyDisplayBufferVdi(IDisplayBufferVdi* vdi);
240```
241
2422. Build a shared library.
243
244   Build a shared library named **libdisplay_buffer_vdi_impl.z.so**. Write the **BUILD.gn** file. You can obtain the **BUILD.gn** file of rk3568 from [https://gitee.com/openharmony/device_soc_rockchip/blob/master/rk3568/hardware/display/BUILD.gn](https://gitee.com/openharmony/device_soc_rockchip/blob/master/rk3568/hardware/display/BUILD.gn).
245
246```
247  ohos_shared_library("libdisplay_buffer_vdi_impl") {
248    sources = [ "src/display_gralloc/display_buffer_vdi_impl.cpp" ]
249
250    public_configs = [ ":libdisplay_buffer_vdi_impl_config" ]
251
252    include_dirs = [
253      "./src/display_gralloc",
254      "${root_path}/drivers/peripheral/base",
255      "${root_path}/drivers/interface/display/composer/hdifd_parcelable",
256      "${root_path}/drivers/interface/display/buffer",
257      "${root_path}/drivers/peripheral/display/utils/include",
258      "${root_path}/drivers/peripheral/display/buffer/hdi_service/include",
259    ]
260
261    output_name = "libdisplay_buffer_vdi_impl"
262    cflags = [
263      "-DGRALLOC_GBM_SUPPORT",
264      "-Wno-macro-redefined",
265    ]
266    deps = [ ":libdisplay_buffer_vendor" ]
267
268    external_deps = [
269      "c_utils:utils",
270      "drivers_interface_display:display_buffer_idl_headers",
271      "drivers_interface_display:display_composer_idl_headers",
272      "hdf_core:libhdf_utils",
273      "hilog:libhilog",
274      "ipc:ipc_single",
275    ]
276
277    install_enable = true
278    install_images = [ chipset_base_dir ]
279    innerapi_tags = [ "passthrough" ]
280    subsystem_name = "hdf"
281    part_name = "rockchip_products"
282  }
283```
284
285In the root directory of your project, run the following command to build the share library:
286
287```
288  ./build.sh -p rk3568 -T display_buffer_model
289```
290Then, you can find **libdisplay_buffer_vdi_impl.z.so** in the **out/rk3568/hdf/rockchip_products** directory.
291
292#### Development Example
293
294A default VDI implementation is provided for your reference. For details, see **drivers/peripheral/display/buffer/vdi_base** at [https://gitee.com/openharmony/drivers_peripheral/tree/master/display/buffer/vdi_base](https://gitee.com/openharmony/drivers_peripheral/tree/master/display/buffer/vdi_base).
295