diff --git a/en/device_api/hdi/display/display_device.h b/en/device_api/hdi/display/display_device.h new file mode 100644 index 0000000000000000000000000000000000000000..af285b46ae6357ff66885e1f16ca12dc95c9bc5d --- /dev/null +++ b/en/device_api/hdi/display/display_device.h @@ -0,0 +1,724 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Display + * @{ + * + * @brief Defines driver functions of the display module. + * + * This module provides driver functions for the graphics subsystem, including graphics layer management, + * device control, graphics hardware acceleration, display memory management, and callbacks. + * @since 1.0 + * @version 2.0 + */ + + /** + * @file display_device.h + * + * @brief Declares control functions of the display device. + * + * @since 1.0 + * @version 2.0 + */ + +#ifndef DISPLAY_DEVICE_H +#define DISPLAY_DEVICE_H +#include "display_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/* * + * @brief Called when a hot plug event occurs. + * + * This callback must be registered by calling RegHotPlugCallback. + * + * @param devId Indicates the ID of the display device. This ID is generated by the HDI implementation layer and + * transferred to the graphics service through the current callback. It identifies the display device to connect. + * @param connected Indicates the connection status of the display device. The value true means that the + * display device is connected, and false means the opposite. + * @param data Indicates the private data carried by the graphics service. This parameter carries the private data + * address transferred when RegHotPlugCallback is called. For details, see {@link RegHotPlugCallback}. + * + * + * @since 1.0 + * @version 1.0 + */ +typedef void (*HotPlugCallback)(uint32_t devId, bool connected, void *data); + +/* * + * @brief Called when a VBLANK event occurs. + * + * This callback must be registered by calling RegDisplayVBlankCallback. + * + * @param sequence Indicates the VBLANK sequence, which is an accumulated value. + * @param ns Indicates the timestamp (in ns) of the VBLANK event. + * @param data Indicates the pointer to the private data carried by the graphics service. This parameter carries + * the address passed when RegDisplayVBlankCallback is called. + * + * @since 1.0 + * @version 1.0 + */ +typedef void (*VBlankCallback)(unsigned int sequence, uint64_t ns, void *data); + +/* * + * @brief Called when the graphics service needs to refresh data frames. + * + * This callback must be registered by calling RegDisplayRefreshCallback. + * + * @param devId Indicates the ID of the display device. + * @param data Indicates the pointer to the private data carried by the graphics service. This parameter carries + * the address passed when RegDisplayRefreshCallback is called. + * + * @since 1.0 + * @version 1.0 + */ +typedef void (*RefreshCallback)(uint32_t devId, void *data); + +/** + * @brief Defines pointers to the functions of the display device. + */ +typedef struct { + /* * + * @brief Registers the callback to be invoked when a hot plug event occurs. + * + * @param callback Indicates the instance used to notify the graphics service of a hot plug event occurred. + * @param data Indicates the pointer to the private data returned to the graphics service in the + * HotPlugCallback callback. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*RegHotPlugCallback)(HotPlugCallback callback, void *data); + + /* * + * @brief Registers the callback to be invoked when a VBLANK event occurs. + * + * @param devId Indicates the ID of the display device. + * @param callback Indicates the instance used to notify the graphics service of the VBLANK event occurred when + * DisplayVsync is enabled. + * @param data Indicates the pointer to the private data returned to the graphics service in the + * VBlankCallback callback. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*RegDisplayVBlankCallback)(uint32_t devId, VBlankCallback callback, void *data); + + /* * + * @brief Called when the graphics service needs to refresh data frames. + * + * @param devId Indicates the ID of the display device. + * @param callback Indicates the instance used to notify the graphics service of the request for refreshing + * data frames. + * @param data Indicates the pointer to the private data returned to the graphics service in the + * RefreshCallback callback. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*RegDisplayRefreshCallback)(uint32_t devId, RefreshCallback callback, void *data); + + /* * + * @brief Obtains the capabilities of a display device. + * + * @param devId Indicates the ID of the display device. + * @param info Indicates the pointer to the capabilities supported by the display device. For details, + * see {@link DisplayCapability}. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayCapability)(uint32_t devId, DisplayCapability *info); + + /* * + * @brief Obtains the display modes supported by a display device. + * + * @param devId Indicates the ID of the display device. + * @param num Indicates the pointer to the number of modes supported by the display device. + * @param modes Indicates the pointer to the information about all modes supported by the display device, + * including all supported resolutions and refresh rates. Each mode has an ID, which will be used when + * the mode is set or obtained. For details, see {@link DisplayModeInfo}. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplaySupportedModes)(uint32_t devId, uint32_t *num, DisplayModeInfo *modes); + + /* * + * @brief Obtains the current display mode of a display device. + * + * @param devId Indicates the ID of the display device. + * @param modeId indicates the pointer to the ID of the current display mode of the device. The display mode ID + * is written by this API. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayMode)(uint32_t devId, uint32_t *modeId); + + /* * + * @brief Sets the display mode of a display device. + * + * @param devId Indicates the ID of the display device. + * @param modeId Indicates the ID of the display mode. The device is switched to the display mode specified by + * this parameter in this interface. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayMode)(uint32_t devId, uint32_t modeId); + + /* * + * @brief Obtains the power status of a display device. + * + * @param devId Indicates the ID of the display device. + * @param status Indicates the pointer to the power status of the device. The status is written by this interface. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayPowerStatus)(uint32_t devId, DispPowerStatus *status); + + /* * + * @brief Sets the power status of a display device. + * + * @param devId Indicates the ID of the display device. + * @param status Indicates the power status to set. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayPowerStatus)(uint32_t devId, DispPowerStatus status); + + /* * + * @brief Obtains the backlight value of a display device. + * + * @param devId Indicates the ID of the display device. + * @param level Indicates the pointer to the backlight value of the device. The backlight value is written + * by this interface. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayBacklight)(uint32_t devId, uint32_t *level); + + /* * + * @brief Sets the backlight value for a display device. + * + * @param devId Indicates the ID of the display device. + * @param level Indicates the backlight value to set. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayBacklight)(uint32_t devId, uint32_t level); + + /* * + * @brief Obtains the property for a display device. + * + * @param devId Indicates the ID of the display device. + * @param id Indicates the property ID returned by GetDisplayCapability. + * @param level Indicates the pointer to the property corresponding to the property ID. The property value is + * written by this interface. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayProperty)(uint32_t devId, uint32_t id, uint64_t *value); + + /* * + * @brief Sets the property for a display device. + * + * @param devId Indicates the ID of the display device. + * @param id Indicates the property ID returned by GetDisplayCapability. + * @param value Indicates the property to set. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayProperty)(uint32_t devId, uint32_t id, uint64_t value); + + /* * + * @brief Prepares for the composition to be performed by a display device. + * + * Before the composition, the graphics service needs to notify the display device of the preparation to be made + * through this interface. + * + * @param devId Indicates the ID of the display device. + * @param needFlushFb Indicates the pointer that specifies whether the graphics service needs to reset the display + * framebuffer by using SetDisplayClientBuffer before the commit operation. + * The value true means that the framebuffer needs to be reset, and false means the opposite. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*PrepareDisplayLayers)(uint32_t devId, bool *needFlushFb); + + /* * + * @brief Obtains the layers whose composition types have changed. + * + * In the preparation for composition, the display device changes the composition type for each layer based on + * the composition capability of the device. This function returns the layers whose composition types have changed. + * + * @param devId Indicates the ID of the display device. + * @param num Indicates the pointer to the number of layers whose composition types have changed. + * @param Layers Indicates the pointer to the start address of the layer array. + * @param Layers Indicates the pointer to the start address of the composition type array. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayCompChange)(uint32_t devId, uint32_t *num, uint32_t *Layers, int32_t *type); + + /* * + * @brief Sets the cropped region for a display device. + * + * You can use this interface to set the cropped region of the client buffer of the display device. + * The cropped region cannot exceed the size of the client buffer. + * + * @param devId Indicates the ID of the display device. + * @param rect Indicates the pointer to the cropped region of the client buffer. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayClientCrop)(uint32_t devId, IRect *rect); + + /* * + * @brief Sets the display region for a display device. + * + * @param devId Indicates the ID of the display device. + * @param rect Indicates the pointer to the display region. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayClientDestRect)(uint32_t devId, IRect *rect); + + /* * + * @brief Sets the display buffer for a display device. + * + * The display buffer stores the hardware composition result of the display device. + * + * @param devId Indicates the ID of the display device. + * @param buffer Indicates the pointer to the display buffer. + * @param fence Indicates the sync fence that specifies whether the display buffer can be accessed. The display + * buffer is created and released by the graphics service. It can be accessed only when the sync fence is in the + * signaled state. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayClientBuffer)(uint32_t devId, const BufferHandle *buffer, int32_t fence); + + /* * + * @brief Sets the dirty region for a display device. + * + * The dirty region consists of multiple rectangular regions. The rectangular regions can be refreshed based on + * the settings. + * + * @param devId Indicates the ID of the display device. + * @param num Indicates the number of rectangles. + * @param rect Indicates the pointer to the start address of the rectangle array. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayClientDamage)(uint32_t devId, uint32_t num, IRect *rect); + + /* * + * @brief Enables or disables the vertical sync signal. + * + * When the vertical sync signal is generated, the VBlankCallback callback registered + * by RegDisplayVBlankCallback will be invoked. The vertical sync signal must be enabled when the graphics + * service needs to refresh the display, and disabled when display refresh is not required. The display does not + * need to refresh when VBlankCallback is invoked and the graphics service composes layers and sends the + * composition result to the device for display. + * + * @param devId Indicates the ID of the display device. + * @param enabled Specifies whether to enable the vertical sync signal. The value true means to enable the + * vertical sync signal, and false means to disable it. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode}otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayVsyncEnabled)(uint32_t devId, bool enabled); + + /* * + * @brief Obtains the fences of the display layers after the commit operation. + * + * @param devId Indicates the ID of the display device. + * @param num Indicates the pointer to the number of layers. + * @param layers Indicates the pointer to the start address of the layer array. + * @param fences Indicates the pointer to the start address of the fence array. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayReleaseFence)(uint32_t devId, uint32_t *num, uint32_t *layers, int32_t *fences); + + /* * + * @brief Obtains the color gamuts supported by a display device. + * + * @param devId Indicates the ID of the display device. + * @param num Indicates the pointer to the number of color gamuts supported by the display device. + * @param gamuts Indicates the pointer to the information about all color gamuts supported by the display device. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplaySupportedColorGamuts)(uint32_t devId, uint32_t *num, ColorGamut *gamuts); + + /* * + * @brief Obtains the color gamut of a display device. + * + * @param devId Indicates the ID of the display device. + * @param gamut Indicates the pointer to the color gamut of the device. The color gamut is written + * by this interface. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayColorGamut)(uint32_t devId, ColorGamut *gamut); + + /* * + * @brief Sets the color gamut for a display device. + * + * @param devId Indicates the ID of the display device. + * @param gamut Indicates the color gamut to set. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayColorGamut)(uint32_t devId, ColorGamut gamut); + + /* * + * @brief Obtains the gamut map of a display device. + * + * @param devId Indicates the ID of the display device. + * @param gamutMap Indicates the pointer to the gamut map of the device. The gamut map is written + * by this interface. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayGamutMap)(uint32_t devId, GamutMap *gamutMap); + + /* * + * @brief Sets the gamut map for a display device. + * + * @param devId Indicates the ID of the display device. + * @param gamutMap Indicates the gamut map to set. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayGamutMap)(uint32_t devId, GamutMap gamutMap); + + /* * + * @brief Sets a 4x4 color transformation matrix for a display device. + * + * @param devId Indicates the ID of the display device. + * @param matrix Indicates the pointer to the 4x4 color transformation matrix to set. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetDisplayColorTransform)(uint32_t devId, const float *matrix); + + /* * + * @brief Obtains the HDR capability of a display device. + * + * @param devId Indicates the ID of the display device. + * @param info Indicates the pointer to the HDR capability of the device. The info is written + * by this interface. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetHDRCapabilityInfos)(uint32_t devId, HDRCapability *info); + + /* * + * @brief Obtains the HDR metadata keys supported by a display device. + * + * @param devId Indicates the ID of the display device. + * @param num Indicates the pointer to the number of metadata keys supported by the display device. + * @param keys Indicates the pointer to the information about all HDR metadata keys supported by the display device. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetSupportedMetadataKey)(uint32_t devId, uint32_t *num, HDRMetadataKey *keys); + + /* * + * @brief Commits the request for composition and display. + * + * If there is a hardware composition layer, the composition is performed and the composition result is sent to + * the hardware for display. + * + * @param devId Indicates the ID of the display device. + * @param num Indicates the pointer to the number of layers. + * @param layers Indicates the pointer to the start address of the layer array. + * @param fences Indicates the pointer to the start address of the fence array. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*Commit)(uint32_t devId, int32_t *fence); + + /* * + * @brief Invokes the display device commands. + * + * This function extends the APIs between the graphics service and implementation layer, eliminating the need + * to add new APIs. + * + * @param devId Indicates the ID of the display device. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*InvokeDisplayCmd)(uint32_t devId, ...); + + /* * + * @brief Creates a virtual display device. + * + * @param width Indicates the pixel width of the display device. + * @param height Indicates the pixel height of the display device. + * @param format Indicates the pointer to the pixel format of the display device. + * For details, see {@link PixelFormat}. The format can be modified based on hardware requirements and + * returned to the graphics service. + * @param devId Indicates the pointer to the ID of the virtual display device created. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*CreateVirtualDisplay)(uint32_t width, uint32_t height, int32_t *format, uint32_t *devId); + + /* * + * @brief Destroys a virtual display device. + * + * @param devId Indicates the ID of the display device. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*DestroyVirtualDisplay)(uint32_t devId); + + /* * + * @brief Sets the output buffer for a virtual display device. + * + * This buffer stores the output of the virtual display device. The buffer can be used only after the sync fence + * is in the signaled state. + * + * @param devId Indicates the ID of the display device. + * @param buffer Indicates the pointer to the output buffer. + * @param fence Indicates the sync fence. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetVirtualDisplayBuffer)(uint32_t devId, BufferHandle *buffer, int32_t fence); + + /* * + * @brief Obtains the writeback frame of a display device. + * + * This function is used to obtain data of the writeback endpoint specified by devId. The data is written + * to the specified buffer by this interface. + * + * @param devId Indicates the ID of the display device. + * @param buffer Indicates the pointer to the buffer of the writeback endpoint data. + * @param fence Indicates the pointer to the sync fence. When calling this interface, the graphics service needs + * to pass the release fence of the buffer to + * specify whether data can be written to the buffer. Then, acquire fence of the buffer needs to be written + * and sent to the graphics service to specify whether the writeback data has been written to the buffer. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetWriteBackFrame)(uint32_t devId, BufferHandle *buffer, int32_t *fence); + + /* * + * @brief Creates a writeback endpoint for a display device. + * + * If the number of writeback endpoints exceeds the limit, a failure message will be returned. + * + * @param devId Indicates the pointer to the ID of the display device. After a writeback endpoint is created, the + * device ID of the writeback endpoint is written in this parameter and returned to the graphics service. + * @param width Indicates the writeback pixel width. + * @param height Indicates the writeback pixel height. + * @param format Indicates the pointer to the writeback point data format. For details, see {@link PixelFormat}. + * The format can be modified based on hardware requirements and returned to the graphics service. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*CreateWriteBack)(uint32_t *devId, uint32_t width, uint32_t height, int32_t *format); + + /* * + * @brief Destroys the writeback endpoint of a display device. + * + * @param devId Indicates the ID of the display device. + * + * @return Returns 0 if the operation is successful; + * @returns an error code defined in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ + int32_t (*DestroyWriteBack)(uint32_t devId); +} DeviceFuncs; + +/** + * @brief Initializes the control functions of a display device. You can apply for resources for + * using control functions and then operate the display device by using the control functions. + * + * @param funcs Indicates the double pointer to the control functions of the display device. The caller obtains + * the double pointer to operate the display device. The memory is allocated during initialization, and therefore + * the caller does not need to allocate the memory. + * + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link DispErrCode} otherwise. + * + * @since 1.0 + * @version 1.0 + */ +int32_t DeviceInitialize(DeviceFuncs **funcs); + +/** + * @brief Uninitializes control functions of the display device. The resources used by the control functions will be + * released. In other words, the memory allocated during initialization of the control functions will be released. + * + * @param funcs Indicates the double pointer to the control functions of the display device. + * + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link DispErrCode} otherwise. + * @since 1.0 + * @version 1.0 + */ +int32_t DeviceUninitialize(DeviceFuncs *funcs); + +#ifdef __cplusplus +} +#endif +#endif +/* @} */ diff --git a/en/device_api/hdi/display/display_gfx.h b/en/device_api/hdi/display/display_gfx.h new file mode 100644 index 0000000000000000000000000000000000000000..1b9e770fc3f7380fb00ac39bd52655d6dcdf73b2 --- /dev/null +++ b/en/device_api/hdi/display/display_gfx.h @@ -0,0 +1,196 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Display + * @{ + * + * @brief Defines driver functions of the display module. + * + * This module provides driver functions for the graphics subsystem, including graphics layer management, + * device control, graphics hardware acceleration, display memory management, and callbacks. + * + * @since 1.0 + * @version 2.0 + */ + +/** + * @file display_gfx.h + * + * @brief Declares the driver functions for implementing hardware acceleration. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef DISPLAY_GFX_H +#define DISPLAY_GFX_H +#include "display_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Defines pointers to the hardware acceleration driver functions. + */ +typedef struct { + /** + * @brief Initializes hardware acceleration. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see DeinitGfx + * @since 1.0 + * @version 1.0 + */ + int32_t (*InitGfx)(void); + + /** + * @brief Deinitializes hardware acceleration. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see InitGfx + * @since 1.0 + * @version 1.0 + */ + int32_t (*DeinitGfx)(void); + + /** + * @brief Fills a rectangle with a given color on the canvas. + * + * @param surface Indicates the pointer to the canvas. + * @param rect Indicates the pointer to the rectangle to fill. + * @param color Indicates the color to fill. + * @param opt Indicates the pointer to the hardware acceleration option. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*FillRect)(ISurface *surface, IRect *rect, uint32_t color, GfxOpt *opt); + + /** + * @brief Draws a rectangle with a given color on the canvas. + * + * @param surface Indicates the pointer to the canvas. + * @param rect Indicates the pointer to the rectangle to draw. + * @param color Indicates the color to draw. + * @param opt Indicates the pointer to the hardware acceleration option. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*DrawRectangle)(ISurface *surface, Rectangle *rect, uint32_t color, GfxOpt *opt); + + /** + * @brief Draws a straight line with a given color on the canvas. + * + * @param surface Indicates the pointer to the canvas. + * @param line Indicates the pointer to the line to draw. + * @param opt Indicates the pointer to the hardware acceleration option. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*DrawLine)(ISurface *surface, ILine *line, GfxOpt *opt); + + /** + * @brief Draws a circle with a specified center and radius on the canvas using a given color. + * + * @param surface Indicates the pointer to the canvas. + * @param circle Indicates the pointer to the circle to draw. + * @param opt Indicates the pointer to the hardware acceleration option. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*DrawCircle)(ISurface *surface, ICircle *circle, GfxOpt *opt); + + /** + * @brief Blits bitmaps. + * + * During bit blit, color space conversion (CSC), scaling, and rotation can be implemented. + * + * @param srcSurface Indicates the pointer to the source bitmap. + * @param srcRect Indicates the pointer to the rectangle of the source bitmap. + * @param dstSurface Indicates the pointer to the destination bitmap. + * @param dstRect Indicates the pointer to the rectangle of the destination bitmap. + * @param opt Indicates the pointer to the hardware acceleration option. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*Blit)(ISurface *srcSurface, IRect *srcRect, ISurface *dstSurface, IRect *dstRect, GfxOpt *opt); + + /** + * @brief Synchronizes hardware acceleration when it is used to draw and blit bitmaps. + * + * This function blocks the process until hardware acceleration is complete. + * + * @param timeOut Indicates the timeout duration for hardware acceleration synchronization. The value 0 + * indicates no timeout, so the process waits until hardware acceleration is complete. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*Sync)(int32_t timeOut); +} GfxFuncs; + +/** + * @brief Initializes the hardware acceleration module to obtain the pointer to functions for hardware acceleration + * operations. + * + * @param funcs Indicates the double pointer to functions for hardware acceleration operations. Memory is allocated + * automatically when you initiate the hardware acceleration module, so you can simply use the pointer to gain access + * to the functions. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ +int32_t GfxInitialize(GfxFuncs **funcs); + +/** + * @brief Deinitializes the hardware acceleration module to release the pointer to functions for hardware + * acceleration operations. + * + * @param funcs Indicates the pointer to the functions for hardware acceleration operations. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ +int32_t GfxUninitialize(GfxFuncs *funcs); + +#ifdef __cplusplus +} +#endif +#endif +/** @} */ diff --git a/en/device_api/hdi/display/display_gralloc.h b/en/device_api/hdi/display/display_gralloc.h new file mode 100644 index 0000000000000000000000000000000000000000..288232c0da326e6bbbbce5bf9647242a55326cd3 --- /dev/null +++ b/en/device_api/hdi/display/display_gralloc.h @@ -0,0 +1,189 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Display + * @{ + * + * @brief Defines driver functions of the display module. + * + * This module provides driver functions for the graphics subsystem, including graphics layer management, + * device control, graphics hardware acceleration, display memory management, and callbacks. + * @since 1.0 + * @version 2.0 + */ + + +/** + * @file display_gralloc.h + * + * @brief Declares the driver functions for memory. + * + * @since 1.0 + * @version 2.0 + */ + +#ifndef DISPLAY_GRALLOC_H +#define DISPLAY_GRALLOC_H +#include "display_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Defines pointers to the memory driver functions. + */ +typedef struct { + /** + * @brief Allocates memory based on the parameters passed by the GUI. + * + * @param info Indicates the pointer to the description info of the memory to allocate. + * + * @param handle Indicates the double pointer to the buffer of the memory to allocate. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*AllocMem)(const AllocInfo* info, BufferHandle** handle); + + /** + * @brief Releases memory. + * + * @param handle Indicates the pointer to the buffer of the memory to release. + * + * @since 1.0 + * @version 1.0 + */ + void (*FreeMem)(BufferHandle *handle); + + /** + * @brief Maps memory to memory without cache in the process's address space. + * + * @param handle Indicates the pointer to the buffer of the memory to map. + * + * @return Returns the pointer to a valid address if the operation is successful; returns NULL otherwise. + * @since 1.0 + * @version 1.0 + */ + void *(*Mmap)(BufferHandle *handle); + + /** + * @brief Maps memory to memory with cache in the process's address space. + * + * @param handle Indicates the pointer to the buffer of the memory to map. + * + * @return Returns the pointer to a valid address if the operation is successful; returns NULL otherwise. + * @since 1.0 + * @version 1.0 + */ + void *(*MmapCache)(BufferHandle *handle); + + /** + * @brief Unmaps memory, that is, removes any mappings from the process's address space. + * + * @param handle Indicates the pointer to the buffer of the memory to unmap. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*Unmap)(BufferHandle *handle); + + /** + * @brief Flushes data from the cache to memory and invalidates the data in the cache. + * + * @param handle Indicates the pointer to the buffer of the cache to flush. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*FlushCache)(BufferHandle *handle); + + /** + * @brief Flushes data from the cache mapped via {@link Mmap} to memory and invalidates the data in the cache. + * + * @param handle Indicates the pointer to the buffer of the cache to flush. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*FlushMCache)(BufferHandle *handle); + + /** + * @brief Invalidates the cache to update it from memory. + * + * @param handle Indicates the pointer to the buffer of the cache, which will been invalidated. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*InvalidateCache)(BufferHandle* handle); + + /** + * @brief Checks whether the given VerifyAllocInfo array is allocatable. + * + * @param num Indicates the size of infos array. + * @param infos Indicates the pointer to the VerifyAllocInfo array. + * @param supporteds Indicates the pointer to the array that can be allocated. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*IsSupportedAlloc)(uint32_t num, const VerifyAllocInfo *infos, bool *supporteds); +} GrallocFuncs; + +/** + * @brief Initializes the memory module to obtain the pointer to functions for memory operations. + * + * @param funcs Indicates the double pointer to functions for memory operations. Memory is allocated automatically when + * you initiate the memory module initialization, so you can simply use the pointer to gain access to the functions. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ +int32_t GrallocInitialize(GrallocFuncs **funcs); + +/** + * @brief Deinitializes the memory module to release the memory allocated to the pointer to functions for memory + * operations. + * + * @param funcs Indicates the pointer to functions for memory operations. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ +int32_t GrallocUninitialize(GrallocFuncs *funcs); + +#ifdef __cplusplus +} +#endif +#endif +/** @} */ diff --git a/en/device_api/hdi/display/display_layer.h b/en/device_api/hdi/display/display_layer.h new file mode 100644 index 0000000000000000000000000000000000000000..2576042c92d93f68d86a4984b21a66eb6f8960b3 --- /dev/null +++ b/en/device_api/hdi/display/display_layer.h @@ -0,0 +1,781 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Display + * @{ + * + * @brief Defines driver functions of the display module. + * + * This module provides driver functions for the graphics subsystem, including graphics layer management, + * device control, graphics hardware acceleration, display memory management, and callbacks. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file display_layer.h + * + * @brief Declares the driver functions for implementing layer operations. + * + * @since 1.0 + * @version 2.0 + */ + +#ifndef DISPLAY_LAYTER_H +#define DISPLAY_LAYTER_H +#include "display_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Defines pointers to the layer driver functions. + */ +typedef struct { + /** + * @brief Initializes a display device. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see DeinitDisplay + * @since 1.0 + * @version 1.0 + */ + int32_t (*InitDisplay)(uint32_t devId); + + /** + * @brief Deinitializes a display device. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see InitDisplay + * @since 1.0 + * @version 1.0 + */ + int32_t (*DeinitDisplay)(uint32_t devId); + + /** + * @brief Obtains information about a display device. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param dispInfo Indicates the pointer to the display device information obtained. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDisplayInfo)(uint32_t devId, DisplayInfo *dispInfo); + + /** + * @brief Opens a layer on a specified display device. + * + * Before using a layer on the GUI, you must open the layer based on the layer information. After the layer is + * opened, you can obtain the layer ID and then use other functions based on the layer ID. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerInfo Indicates the pointer to the layer information passed to open a layer, including the layer + * type, layer size, and pixel format. + * @param layerId Indicates the pointer to the layer ID, which uniquely identifies a layer. The layer ID is returned + * to the GUI after the layer is successfully opened. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see CloseLayer + * @since 1.0 + * @version 1.0 + */ + + int32_t (*CreateLayer)(uint32_t devId, const LayerInfo *layerInfo, uint32_t *layerId); + /** + * @brief Closes a layer that is no longer required on a specified display device. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see OpenLayer + * @since 1.0 + * @version 1.0 + */ + int32_t (*CloseLayer)(uint32_t devId, uint32_t layerId); + + /** + * @brief Sets whether a layer is visible. + * + * A visible layer is displayed on the screen, whereas an invisible layer is not displayed on the screen. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param visible Indicates the visibility to set for the layer. The value true means to set the layer to be + * visible, and false means the opposite. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see GetLayerVisibleState + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerVisible)(uint32_t devId, uint32_t layerId, bool visible); + + /** + * @brief Checks whether a layer is visible. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param visible Indicates the pointer to the obtained layer visibility. The value true indicates that the + * layer is visible, and false indicates that the layer is invisible. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see SetLayerVisible + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerVisibleState)(uint32_t devId, uint32_t layerId, bool *visible); + + /** + * @brief Sets the size of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param rect Indicates the pointer to the layer size to set, in pixels. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see GetLayerSize + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerSize)(uint32_t devId, uint32_t layerId, IRect *rect); + + /** + * @brief Obtains the size of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param rect Indicates the pointer to the obtained layer size. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see SetLayerSize + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerSize)(uint32_t devId, uint32_t layerId, IRect *rect); + + /** + * @brief Sets the rectangular area to crop for a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param rect Indicates the pointer to the rectangular area to crop. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerCrop)(uint32_t devId, uint32_t layerId, IRect *rect); + + /** + * @brief Sets the z-order for a layer. + * + * A larger z-order value indicates a higher layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param zorder Indicates the z-order to set. The value is an integer ranging from 0 to 255. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see GetLayerZorder + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerZorder)(uint32_t devId, uint32_t layerId, uint32_t zorder); + + /** + * @brief Obtains the z-order of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param zorder Indicates the pointer to the obtained z-order. The value is an integer ranging from 0 to 255. + * A larger z-order value indicates a higher layer. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see SetLayerZorder + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerZorder)(uint32_t devId, uint32_t layerId, uint32_t *zorder); + + /** + * @brief Sets layer premultiplication. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param preMul Specifies whether to enable layer premultiplication. The value 1 means to enable layer + * premultiplication, and 0 means the opposite. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see GetLayerPreMulti + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerPreMulti)(uint32_t devId, uint32_t layerId, bool preMul); + + /** + * @brief Obtains the premultiplication flag of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param preMul Indicates the pointer to the obtained layer premultiplication flag. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see SetLayerPreMulti + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerPreMulti)(uint32_t devId, uint32_t layerId, bool *preMul); + + /** + * @brief Sets the alpha value for a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param alpha Indicates the pointer to the alpha value to set. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see GetLayerAlpha + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerAlpha)(uint32_t devId, uint32_t layerId, LayerAlpha *alpha); + + /** + * @brief Obtains the alpha value of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param alpha Indicates the pointer to the obtained alpha value. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see SetLayerAlpha + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerAlpha)(uint32_t devId, uint32_t layerId, LayerAlpha *alpha); + + /** + * @brief Sets the color key for a layer. The color key is used during layer overlay. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param enable Specify whether to enable the color key. + * @param key Indicates the color key. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see GetLayerColorKey + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerColorKey)(uint32_t devId, uint32_t layerId, bool enable, uint32_t key); + + /** + * @brief Obtains the color key of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param enable Indicates the pointer to the color key enable bit. + * @param key Indicates the pointer to the color key. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see SetLayerColorKey + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerColorKey)(uint32_t devId, uint32_t layerId, bool *enable, uint32_t *key); + + /** + * @brief Sets the palette for a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param palette Indicates the pointer to the palette to set. + * @param len Indicates the length of the palette. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see GetLayerPalette + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerPalette)(uint32_t devId, uint32_t layerId, uint32_t *palette, uint32_t len); + + /** + * @brief Obtains the palette of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param palette Indicates the pointer to the obtained palette. + * @param len Indicates the length of the palette. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see SetLayerPalette + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerPalette)(uint32_t devId, uint32_t layerId, uint32_t *palette, uint32_t len); + + /** + * @brief Sets the transform mode for rotating, scaling, or moving a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param type Indicates the transformation mode to set. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetTransformMode)(uint32_t devId, uint32_t layerId, TransformType type); + + /** + * @brief Sets the compression feature for a layer. + * + * In specific scenarios, images need to be compressed. You can set whether to enable layer compression. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param compType Specifies whether to enable the compression feature. The value true>/b> means to enable + * compression, and false> means the opposite. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see GetLayerCompression + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerCompression)(uint32_t devId, uint32_t layerId, int32_t compType); + + /** + * @brief Checks whether the compression feature is enabled for a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param compType Indicates the pointer to the variable specifying whether the compression feature is enabled. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see SetLayerCompression + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerCompression)(uint32_t devId, uint32_t layerId, int32_t *compType); + + /** + * @brief Sets the flushing area for a layer. + * + * After the GUI draws an image, you must set the layer flushing area before calling the {@link Flush} function to + * flush the screen. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param region Indicates the pointer to the flushing area to set. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerDirtyRegion)(uint32_t devId, uint32_t layerId, IRect *region); + + /** + * @brief Obtains the buffer of a layer. + * + * After drawing a picture in the buffer, the application calls the {@link Flush} function to display the picture + * on the screen. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param buffer Indicates the pointer to the obtained buffer. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see Flush + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerBuffer)(uint32_t devId, uint32_t layerId, LayerBuffer *buffer); + + /** + * @brief Flushes a layer. + * + * Display data in the buffer is flushed to a specified layer so that the image data is displayed on the screen. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param buffer Indicates the pointer to the buffer in which the display data is to flush. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*Flush)(uint32_t devId, uint32_t layerId, LayerBuffer *buffer); + + /** + * @brief Waits for the arrival of vertical blanking. + * + * This function blocks the process until vertical blanking arrives, implementing the synchronization between + * software and hardware. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param timeOut Indicates the maximum duration that the process waits for the arrival of vertical blanking. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*WaitForVBlank)(uint32_t devId, uint32_t layerId, int32_t timeOut); + + /** + * @brief Implements the snapshot feature. + * + * This function saves the screenshot of image data on the display device to the buffer for debugging or as + * requested by applications. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param buffer Indicates the pointer to the buffer for saving screenshots. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SnapShot)(uint32_t devId, LayerBuffer *buffer); + + /** + * @brief Set the visible region for a layer + * + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param num Indicates the count of rect. the region contains multiple IRect, the num means how much rects in the + * region. + * @param rect Indicates the pointer of the rectes. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 2.0 + * @version 2.0 + */ + int32_t (*SetLayerVisibleRegion)(uint32_t devId, uint32_t layerId, uint32_t num, IRect *rect); + + /** + * @brief Set the buffer for a layer. + * + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param buffer Indicates the pointer of the buffer handle. The buffer handle should contain all information of the + * buffer which will be used for composition. + * @param fence Indicates the fd of a sync file. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 2.0 + * @version 2.0 + */ + int32_t (*SetLayerBuffer)(uint32_t devId, uint32_t layerId, const BufferHandle *buffer, int32_t fence); + + /** + * @brief Extension interface + * + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param cmd Indicates extension cmd to be used to identify different intention. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 2.0 + * @version 2.0 + */ + int32_t (*InvokeLayerCmd)(uint32_t devId, uint32_t layerId, uint32_t cmd, ...); + + /** + * @brief set the composition type which the client expect + * + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param type Indicates the composition type which the client expect. It may vary with the implementation. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 2.0 + * @version 2.0 + */ + int32_t (*SetLayerCompositionType)(uint32_t devId, uint32_t layerId, CompositionType type); + + /** + * @brief set the blend type + * + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param type Indicates blend type + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 2.0 + * @version 2.0 + */ + int32_t (*SetLayerBlendType)(uint32_t devId, uint32_t layerId, BlendType type); + + /** + * @brief Sets a 4x4 color transformation matrix. + * + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param matrix Indicates the 4x4 color transformation matrix. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerColorTransform)(uint32_t devId, uint32_t layerId, const float *matrix); + + /** + * @brief Sets a color data space for a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param colorSpace Indicates the color data space to set. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerColorDataSpace)(uint32_t devId, uint32_t layerId, ColorDataSpace colorSpace); + + /** + * @brief Obtains the color data space of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param colorSpace Indicates the pointer to the color data space obtained. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetLayerColorDataSpace)(uint32_t devId, uint32_t layerId, ColorDataSpace *colorSpace); + + /** + * @brief Sets metadata for a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param num Indicates the number of metadata records. + * @param metaData Indicates the pointer to the metadata to set. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerMetaData)(uint32_t devId, uint32_t layerId, uint32_t num, const HDRMetaData *metaData); + + /** + * @brief Sets a metadata set for a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param key Indicates the metadata key. + * @param num Indicates the number of metadata records. + * @param metaData Indicates the pointer to the metadata set of the uint8_t type to set. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetLayerMetaDataSet)(uint32_t devId, uint32_t layerId, HDRMetadataKey key, uint32_t num, + const uint8_t *metaData); + + /** + * @brief Obtains the hardware display present timestamp type supported by a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param type Indicates the pointer to the present timestamp type obtained. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetSupportedPresentTimestamp)(uint32_t devId, uint32_t layerId, PresentTimestampType *type); + + /** + * @brief Obtains the hardware display present timestamp of a layer. + * + * @param devId Indicates the ID of the display device. The value ranges from 0 to 4, where 0 indicates the first + * display device, and 4 indicates the last display device. + * @param layerId Indicates the layer ID, which uniquely identifies a layer. You can perform operations on the layer + * with the specified layer ID. + * @param pts Indicates the pointer to the present timestamp obtained. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetHwPresentTimestamp)(uint32_t devId, uint32_t layerId, PresentTimestamp *pts); +} LayerFuncs; + +/** + * @brief Initializes the layer to apply for resources used by the layer and obtain the pointer to functions for + * layer operations. + * + * @param funcs Indicates the double pointer to functions for layer operations. Memory is allocated automatically when + * you initiate the layer module, so you can simply use the pointer to gain access to the functions. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see LayerUninitialize + * @since 1.0 + * @version 1.0 + */ +int32_t LayerInitialize(LayerFuncs **funcs); + +/** + * @brief Deinitializes the layer module to release the memory allocated to the pointer to functions for + * layer operations. + * + * @param funcs Indicates the pointer to functions for layer operations. + * + * @return Returns 0 if the operation is successful; returns an error code defined in {@link DispErrCode} + * otherwise. + * @see LayerInitialize + * @since 1.0 + * @version 1.0 + */ +int32_t LayerUninitialize(LayerFuncs *funcs); + +#ifdef __cplusplus +} +#endif +#endif +/** @} */ diff --git a/en/device_api/hdi/display/display_type.h b/en/device_api/hdi/display/display_type.h new file mode 100644 index 0000000000000000000000000000000000000000..40f9bfd8611ed6aa47043629c1b25d9597de59a8 --- /dev/null +++ b/en/device_api/hdi/display/display_type.h @@ -0,0 +1,638 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Display + * @{ + * + * @brief Defines driver functions of the display module. + * + * This module provides driver functions for the graphics subsystem, including graphics layer management, + * device control, graphics hardware acceleration, display memory management, and callbacks. + * + * @since 1.0 + * @version 2.0 + */ + +/** + * @file display_type.h + * + * @brief Declares the data types used by the display driver functions. + * + * @since 1.0 + * @version 2.0 + */ + +#ifndef DISPLAY_TYPE_H +#define DISPLAY_TYPE_H +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include "buffer_handle.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Enumerates return values of the functions. + * + */ +typedef enum { + DISPLAY_SUCCESS = 0, /**< Success */ + DISPLAY_FAILURE = -1, /**< Failure */ + DISPLAY_FD_ERR = -2, /**< File handle (FD) error */ + DISPLAY_PARAM_ERR = -3, /**< Parameter error */ + DISPLAY_NULL_PTR = -4, /**< Null pointer */ + DISPLAY_NOT_SUPPORT = -5, /**< Unsupported feature */ + DISPLAY_NOMEM = -6, /**< Insufficient memory */ + DISPLAY_SYS_BUSY = -7, /**< System busy */ + DISPLAY_NOT_PERM = -8 /**< Forbidden operation */ +} DispErrCode; + +/** + * @brief Enumerates layer types. + * + */ +typedef enum { + LAYER_TYPE_GRAPHIC, /**< Graphic layer */ + LAYER_TYPE_OVERLAY, /**< Overlay layer */ + LAYER_TYPE_SDIEBAND, /**< Sideband layer */ + LAYER_TYPE_CURSOR, /**< Cursor Layer */ + LAYER_TYPE_BUTT /**< Empty layer */ +} LayerType; + +/* * + * @brief Defines the buffer usage. + * + */ +enum { + HBM_USE_CPU_READ = (1 << 0), /**< CPU read buffer */ + HBM_USE_CPU_WRITE = (1 << 1), /**< CPU write memory */ + HBM_USE_MEM_MMZ = (1 << 2), /**< Media memory zone (MMZ) */ + HBM_USE_MEM_DMA = (1 << 3), /**< Direct memory access (DMA) buffer */ + HBM_USE_MEM_SHARE = (1 << 4), /**< Shared memory buffer*/ + HBM_USE_MEM_MMZ_CACHE = (1 << 5), /**< MMZ with cache*/ + HBM_USE_MEM_FB = (1 << 6), /**< Framebuffer */ + HBM_USE_ASSIGN_SIZE = (1 << 7), /**< Memory assigned */ +}; + +/** + * @brief Enumerates pixel formats. + * + */ +typedef enum { + PIXEL_FMT_CLUT8 = 0, /**< CLUT8 format */ + PIXEL_FMT_CLUT1, /**< CLUT1 format */ + PIXEL_FMT_CLUT4, /**< CLUT4 format */ + PIXEL_FMT_RGB_565, /**< RGB565 format */ + PIXEL_FMT_RGBA_5658, /**< RGBA5658 format */ + PIXEL_FMT_RGBX_4444, /**< RGBX4444 format */ + PIXEL_FMT_RGBA_4444, /**< RGBA4444 format */ + PIXEL_FMT_RGB_444, /**< RGB444 format */ + PIXEL_FMT_RGBX_5551, /**< RGBX5551 format */ + PIXEL_FMT_RGBA_5551, /**< RGBA5551 format */ + PIXEL_FMT_RGB_555, /**< RGB555 format */ + PIXEL_FMT_RGBX_8888, /**< RGBX8888 format */ + PIXEL_FMT_RGBA_8888, /**< RGBA8888 format */ + PIXEL_FMT_RGB_888, /**< RGB888 format */ + PIXEL_FMT_BGR_565, /**< BGR565 format */ + PIXEL_FMT_BGRX_4444, /**< BGRX4444 format */ + PIXEL_FMT_BGRA_4444, /**< BGRA4444 format */ + PIXEL_FMT_BGRX_5551, /**< BGRX5551 format */ + PIXEL_FMT_BGRA_5551, /**< BGRA5551 format */ + PIXEL_FMT_BGRX_8888, /**< BGRX8888 format */ + PIXEL_FMT_BGRA_8888, /**< BGRA8888 format */ + PIXEL_FMT_YUV_422_I, /**< YUV422 interleaved format */ + PIXEL_FMT_YCBCR_422_SP, /**< YCBCR422 semi-planar format */ + PIXEL_FMT_YCRCB_422_SP, /**< YCRCB422 semi-planar format */ + PIXEL_FMT_YCBCR_420_SP, /**< YCBCR420 semi-planar format */ + PIXEL_FMT_YCRCB_420_SP, /**< YCRCB420 semi-planar format */ + PIXEL_FMT_YCBCR_422_P, /**< YCBCR422 planar format */ + PIXEL_FMT_YCRCB_422_P, /**< YCRCB422 planar format */ + PIXEL_FMT_YCBCR_420_P, /**< YCBCR420 planar format */ + PIXEL_FMT_YCRCB_420_P, /**< YCRCB420 planar format */ + PIXEL_FMT_YUYV_422_PKG, /**< YUYV422 packed format */ + PIXEL_FMT_UYVY_422_PKG, /**< UYVY422 packed format */ + PIXEL_FMT_YVYU_422_PKG, /**< YVYU422 packed format */ + PIXEL_FMT_VYUY_422_PKG, /**< VYUY422 packed format */ + PIXEL_FMT_BUTT /**< Invalid pixel format */ +} PixelFormat; + +/** + * @brief Enumerates transform types of images. + * + */ +typedef enum { + ROTATE_NONE = 0, /**< No rotation */ + ROTATE_90, /**< Rotation by 90 degrees */ + ROTATE_180, /**< Rotation by 180 degrees */ + ROTATE_270, /**< Rotation by 270 degrees */ + ROTATE_BUTT /**< Invalid operation */ +} TransformType; + +/** + * @brief Enumerates image blending types. + * + * The system combines images based on a specified blending type during hardware acceleration. + * + */ +typedef enum { + BLEND_NONE = 0, /**< No blending */ + BLEND_CLEAR, /**< CLEAR blending */ + BLEND_SRC, /**< SRC blending */ + BLEND_SRCOVER, /**< SRC_OVER blending */ + BLEND_DSTOVER, /**< DST_OVER blending */ + BLEND_SRCIN, /**< SRC_IN blending */ + BLEND_DSTIN, /**< DST_IN blending */ + BLEND_SRCOUT, /**< SRC_OUT blending */ + BLEND_DSTOUT, /**< DST_OUT blending */ + BLEND_SRCATOP, /**< SRC_ATOP blending */ + BLEND_DSTATOP, /**< DST_ATOP blending */ + BLEND_ADD, /**< ADD blending */ + BLEND_XOR, /**< XOR blending */ + BLEND_DST, /**< DST blending */ + BLEND_AKS, /**< AKS blending */ + BLEND_AKD, /**< AKD blending */ + BLEND_BUTT /**< Null operation */ +} BlendType; + +/** + * @brief Enumerates ROP types supported by hardware acceleration. + * + * ROP performs bitwise Boolean operations (including bitwise AND and bitwise OR) on the RGB color and + * alpha values of the foreground bitmap with those of the background bitmap, and then outputs the result. + * + */ +typedef enum { + ROP_BLACK = 0, /**< Blackness */ + ROP_NOTMERGEPEN, /**< ~(S2+S1) */ + ROP_MASKNOTPEN, /**< ~S2&S1 */ + ROP_NOTCOPYPEN, /**< ~S2 */ + ROP_MASKPENNOT, /**< S2&~S1 */ + ROP_NOT, /**< ~S1 */ + ROP_XORPEN, /**< S2^S1 */ + ROP_NOTMASKPEN, /**< ~(S2&S1) */ + ROP_MASKPEN, /**< S2&S1 */ + ROP_NOTXORPEN, /**< ~(S2^S1) */ + ROP_NOP, /**< S1 */ + ROP_MERGENOTPEN, /**< ~S2+S1 */ + ROP_COPYPE, /**< S2 */ + ROP_MERGEPENNOT, /**< S2+~S1 */ + ROP_MERGEPEN, /**< S2+S1 */ + ROP_WHITE, /**< Whiteness */ + ROP_BUTT /**< Invalid ROP type */ +} RopType; + +/** + * @brief Enumerates color key types supported by hardware acceleration. + * + */ +typedef enum { + CKEY_NONE = 0, /**< No color key */ + CKEY_SRC, /**< Source color key */ + CKEY_DST, /**< Destination color key */ + CKEY_BUTT /**< Null operation */ +} ColorKey; + +/** + * @brief Enumerates mirror types supported by hardware acceleration. + * + */ +typedef enum { + MIRROR_NONE = 0, /**< No mirror */ + MIRROR_LR, /**< Left and right mirrors */ + MIRROR_TB, /**< Top and bottom mirrors */ + MIRROR_BUTT /**< Null operation */ +} MirrorType; + +/** + * @brief Enumerates connection types of hot plugging. + * + */ +typedef enum { + CON_INVALID = 0, /**< Invalid connection */ + CONNECTED, /**< Connected */ + DISCONNECTED /**< Disconnected */ +} Connection; + +/** + * @brief Defines display information. + * + */ +typedef struct { + uint32_t width; /**< Display width */ + uint32_t height; /**< Display height */ + int32_t rotAngle; /**< Rotation angle of the display */ +} DisplayInfo; + +/** + * @brief Defines layer information. + * + * LayerInfo must be passed to the {@link OpenLayer} function, which creates a layer based on the layer + * information. + * + */ +typedef struct { + int32_t width; /**< Layer width */ + int32_t height; /**< Layer height */ + LayerType type; /**< Layer type, which can be a graphic layer, overlay layer, or sideband layer */ + int32_t bpp; /**< Number of bits occupied by each pixel */ + PixelFormat pixFormat; /**< Pixel format of the layer */ +} LayerInfo; + +/** + * @brief Defines alpha information about a layer. + * + */ +typedef struct { + bool enGlobalAlpha; /**< Global alpha enable bit */ + bool enPixelAlpha; /**< Pixel alpha enable bit */ + uint8_t alpha0; /**< Alpha0 value, ranging from 0 to 255 */ + uint8_t alpha1; /**< Alpha1 value, ranging from 0 to 255 */ + uint8_t gAlpha; /**< Global alpha value, ranging from 0 to 255 */ +} LayerAlpha; + + +/** + * @brief Defines buffer data of a layer, including the virtual and physical memory addresses. + * + */ +typedef struct { + uint64_t phyAddr; /**< Physical memory address */ + void *virAddr; /**< Virtual memory address */ +} BufferData; + +/** + * @brief Defines the buffer, which is used to store layer data. + * + */ +typedef struct { + int32_t fenceId; /**< Fence ID of the buffer */ + int32_t width; /**< Buffer width */ + int32_t height; /**< Buffer height */ + int32_t pitch; /**< Number of bytes from one row of pixels in memory to the next */ + PixelFormat pixFormat; /**< Pixel format of the buffer */ + BufferData data; /**< Layer buffer data */ + BufferHandle* hdl; /**< Layer buffer handle */ +} LayerBuffer; + +/** + * @brief Defines the information about a rectangle. + * + */ +typedef struct { + int32_t x; /**< Start X coordinate of the rectangle */ + int32_t y; /**< Start Y coordinate of the rectangle */ + int32_t w; /**< Width of the rectangle */ + int32_t h; /**< Height of the rectangle */ +} IRect; + +/** + * @brief Stores surface information for hardware acceleration, such as draw image and bit blit. + * + */ +typedef struct { + uint64_t phyAddr; /**< Start physical address of an image */ + int32_t height; /**< Image height */ + int32_t width; /**< Image width */ + int32_t stride; /**< Image stride */ + PixelFormat enColorFmt; /**< Image format */ + bool bYCbCrClut; /**< Whether the color lookup table (CLUT) is in the YCbCr space */ + bool bAlphaMax255; /**< Maximum alpha value of an image (255 or 128) */ + bool bAlphaExt1555; /**< ARGB1555 alpha extension enable bit */ + uint8_t alpha0; /**< Value of alpha0, ranging from 0 to 255 */ + uint8_t alpha1; /**< Value of alpha1, ranging from 0 to 255 */ + uint64_t cbcrPhyAddr; /**< CbCr physical address */ + int32_t cbcrStride; /**< CbCr stride */ + uint64_t clutPhyAddr; /**< Start physical address of the CLUT, used for color extension or correction */ +} ISurface; + +/** + * @brief Describes a line to help draw lines in hardware acceleration. + * + */ +typedef struct { + int32_t x0; /**< X coordinate of the start point of a line */ + int32_t y0; /**< Y coordinate of the start point of a line */ + int32_t x1; /**< X coordinate of the end point of a line */ + int32_t y1; /**< Y coordinate of the end point of a line */ + uint32_t color; /**< Line color */ +} ILine; + +/** + * @brief Describes a circle to help draw circles in hardware acceleration. + * + */ +typedef struct { + int32_t x; /**< X coordinate of a circle center */ + int32_t y; /**< Y coordinate of a circle center */ + int32_t r; /**< Radius of a circle */ + uint32_t color; /**< Circle color */ +} ICircle; + +/** + * @brief Describes a rectangle to help draw rectangles in hardware acceleration. + * + */ +typedef struct { + IRect rect; /**< Bounds of a rectangle */ + uint32_t color; /**< Rectangle color */ +} Rectangle; + +/** + * @brief Defines hardware acceleration options. + * + */ +typedef struct { + bool enGlobalAlpha; /**< Global alpha enable bit */ + uint32_t globalAlpha; /**< Global alpha value */ + bool enPixelAlpha; /**< Pixel alpha enable bit */ + BlendType blendType; /**< Blending type */ + ColorKey colorKeyFrom; /**< Color key mode */ + bool enableRop; /**< Raster operations pipeline (ROP) enable bit */ + RopType colorRopType; /**< Color ROP type */ + RopType alphaRopType; /**< Alpha ROP type */ + bool enableScale; /**< Scaling enable bit */ + TransformType rotateType; /**< Rotation type */ + MirrorType mirrorType; /**< Mirror type */ +} GfxOpt; + +#define PROPERTY_NAME_LEN 50 + +/** + * @brief Defines property object which contains name, property id and value. + * + */ +typedef struct { + char name[PROPERTY_NAME_LEN]; /**< Name of the property */ + uint32_t propId; /**< Property id which was decided in the DRM internal */ + uint64_t value; /**< the value of property */ +} PropertyObject; + +/** + * @brief Enumerates interface types. + * + */ +typedef enum { + DISP_INTF_HDMI = 0, /**< HDMI interface */ + DISP_INTF_LCD, /**< LCD interface */ + DISP_INTF_BT1120, /**< BT1120 interface */ + DISP_INTF_BT656, /**< BT656 interface */ + DISP_INTF_YPBPR, /**< YPBPR interface */ + DISP_INTF_RGB, /**< RGB interface */ + DISP_INTF_CVBS, /**< CVBS interface */ + DISP_INTF_SVIDEO, /**< SVIDEO interface */ + DISP_INTF_VGA, /**< VGA interface */ + DISP_INTF_MIPI, /**< MIPI interface */ + DISP_INTF_PANEL, /**< PANEL interface */ + DISP_INTF_BUTT, +} InterfaceType; + +/** + * @brief Defines the capability of the output. + */ +typedef struct { + char name[PROPERTY_NAME_LEN]; /**< Name of the output */ + InterfaceType type; /**< Interface type of the output */ + uint32_t phyWidth; /**< Physical width */ + uint32_t phyHeight; /**< Physical height */ + uint32_t supportLayers; /**< Bitmask of LayerType */ + uint32_t virtualDispCount; /**< Count of virtual displays supported */ + bool supportWriteBack; /**< Whether writeback is supported */ + uint32_t propertyCount; /**< Count of properties */ + PropertyObject* props; /**< Array of property objects */ +} DisplayCapability; + +/** + * @brief Defines output mode info. + */ +typedef struct { + int32_t width; /**< Width in pixel */ + int32_t height; /**< Height in pixel */ + uint32_t freshRate; /**< Fresh rate per second */ + int32_t id; /**< ID of the mode */ +} DisplayModeInfo; + +/** + * @brief Defines information about the memory to allocate. + * + */ +typedef struct { + uint32_t width; /**< Width of the requested memory */ + uint32_t height; /**< Height of the requested memory */ + uint64_t usage; /**< Usage of the requested memory */ + PixelFormat format; /**< Format of the requested memory */ + uint32_t expectedSize; /**< Size assigned by memory requester */ +} AllocInfo; +/** + * @brief Enumerates power status. + */ + +typedef enum { + POWER_STATUS_ON, /**< The power status is on. */ + POWER_STATUS_STANDBY, /**< The power status is standby. */ + POWER_STATUS_SUSPEND, /**< The power status is suspended. */ + POWER_STATUS_OFF, /**< The power status is off. */ + POWER_STATUS_BUTT +} DispPowerStatus; + +/** + * @brief Enumerates the composition types of the special layer. + */ +typedef enum { + COMPOSITION_CLIENT, /**< Client composition type. The composer should be the CPU or GPU. */ + COMPOSITION_DEVICE, /**< Device composition type. The composer should be the hardware. */ + COMPOSITION_CURSOR, /**< Cursor composition type, used for cursor. */ + COMPOSITION_VIDEO, /**< Cursor composition type, used for video. */ + COMPOSITION_BUTT +} CompositionType; + +/** + * @brief Enumerates the color gamuts. + * + */ +typedef enum { + COLOR_GAMUT_INVALID = -1, /**< Invalid */ + COLOR_GAMUT_NATIVE = 0, /**< Native or default */ + COLOR_GAMUT_SATNDARD_BT601 = 1, /**< Standard BT601 */ + COLOR_GAMUT_STANDARD_BT709 = 2, /**< Standard BT709 */ + COLOR_GAMUT_DCI_P3 = 3, /**< DCI P3 */ + COLOR_GAMUT_SRGB = 4, /**< SRGB */ + COLOR_GAMUT_ADOBE_RGB = 5, /**< Adobe RGB */ + COLOR_GAMUT_DISPLAY_P3 = 6, /**< display P3 */ + COLOR_GAMUT_BT2020 = 7, /**< BT2020 */ + COLOR_GAMUT_BT2100_PQ = 8, /**< BT2100 PQ */ + COLOR_GAMUT_BT2100_HLG = 9, /**< BT2100 HLG */ + COLOR_GAMUT_DISPLAY_BT2020 = 10, /**< Display BT2020 */ +} ColorGamut; + +/** + * @brief Enumerates the color gamut maps. + * + */ +typedef enum { + GAMUT_MAP_CONSTANT = 0, + GAMUT_MAP_EXPANSION = 1, + GAMUT_MAP_HDR_CONSTANT = 2, + GAMUT_MAP_HDR_EXPANSION = 3, +} GamutMap; + +/** + * @brief Enumerates the color data spaces. + * + */ + +typedef enum { + COLOR_DATA_SPACE_UNKNOWN = 0, + GAMUT_BT601 = 0x00000001, + GAMUT_BT709 = 0x00000002, + GAMUT_DCI_P3 = 0x00000003, + GAMUT_SRGB = 0x00000004, + GAMUT_ADOBE_RGB = 0x00000005, + GAMUT_DISPLAY_P3 = 0x00000006, + GAMUT_BT2020 = 0x00000007, + GAMUT_BT2100_PQ = 0x00000008, + GAMUT_BT2100_HLG = 0x00000009, + GAMUT_DISPLAY_BT2020 = 0x0000000a, + TRANSFORM_FUNC_UNSPECIFIED = 0x00000100, + TRANSFORM_FUNC_LINEAR = 0x00000200, + TRANSFORM_FUNC_SRGB = 0x00000300, + TRANSFORM_FUNC_SMPTE_170M = 0x00000400, + TRANSFORM_FUNC_GM2_2 = 0x00000500, + TRANSFORM_FUNC_GM2_6 = 0x00000600, + TRANSFORM_FUNC_GM2_8 = 0x00000700, + TRANSFORM_FUNC_ST2084 = 0x00000800, + TRANSFORM_FUNC_HLG = 0x00000900, + PRECISION_UNSPECIFIED = 0x00010000, + PRECISION_FULL = 0x00020000, + PRESION_LIMITED = 0x00030000, + PRESION_EXTENDED = 0x00040000, + BT601_SMPTE170M_FULL = GAMUT_BT601 | TRANSFORM_FUNC_SMPTE_170M | PRECISION_FULL, + BT601_SMPTE170M_LIMITED = GAMUT_BT601 | TRANSFORM_FUNC_SMPTE_170M | PRESION_LIMITED, + BT709_LINEAR_FULL = GAMUT_BT709 | TRANSFORM_FUNC_LINEAR | PRECISION_FULL, + BT709_LINEAR_EXTENDED = GAMUT_BT709 | TRANSFORM_FUNC_LINEAR | PRESION_EXTENDED, + BT709_SRGB_FULL = GAMUT_BT709 | TRANSFORM_FUNC_SRGB | PRECISION_FULL, + BT709_SRGB_EXTENDED = GAMUT_BT709 | TRANSFORM_FUNC_SRGB | PRESION_EXTENDED, + BT709_SMPTE170M_LIMITED = GAMUT_BT709 | TRANSFORM_FUNC_SMPTE_170M | PRESION_LIMITED, + DCI_P3_LINEAR_FULL = GAMUT_DCI_P3 | TRANSFORM_FUNC_LINEAR | PRECISION_FULL, + DCI_P3_GAMMA26_FULL = GAMUT_DCI_P3 | TRANSFORM_FUNC_GM2_6 | PRECISION_FULL, + DISPLAY_P3_LINEAR_FULL = GAMUT_DISPLAY_P3 | TRANSFORM_FUNC_LINEAR | PRECISION_FULL, + DCI_P3_SRGB_FULL = GAMUT_DCI_P3 | TRANSFORM_FUNC_SRGB | PRECISION_FULL, + ADOBE_RGB_GAMMA22_FULL = GAMUT_ADOBE_RGB | TRANSFORM_FUNC_GM2_2 | PRECISION_FULL, + BT2020_LINEAR_FULL = GAMUT_BT2020 | TRANSFORM_FUNC_LINEAR | PRECISION_FULL, + BT2020_SRGB_FULL = GAMUT_BT2020 | TRANSFORM_FUNC_SRGB | PRECISION_FULL, + BT2020_SMPTE170M_FULL = GAMUT_BT2020 | TRANSFORM_FUNC_SMPTE_170M | PRECISION_FULL, + BT2020_ST2084_FULL = GAMUT_BT2020 | TRANSFORM_FUNC_ST2084 | PRECISION_FULL, + BT2020_HLG_FULL = GAMUT_BT2020 | TRANSFORM_FUNC_HLG | PRECISION_FULL, + BT2020_ST2084_LIMITED = GAMUT_BT2020 | TRANSFORM_FUNC_ST2084 | PRESION_LIMITED, +} ColorDataSpace; + +/** + * @brief Enumerates the HDR formats. + * + */ +typedef enum { + NOT_SUPPORT_HDR = 0, + DOLBY_VISION = 1, + HDR10 = 2, + HLG = 3, + HDR10_PLUS = 4, + HDR_VIVID = 5, +} HDRFormat; + +/** + * @brief Defines the HDR capability. + * + */ +typedef struct { + uint32_t formatCount; + HDRFormat* formats; + float maxLum; + float maxAverageLum; + float minLum; +} HDRCapability; + +/** + * @brief Enumerates the HDR metadata keys. + * + */ +typedef enum { + MATAKEY_RED_PRIMARY_X = 0, + MATAKEY_RED_PRIMARY_Y = 1, + MATAKEY_GREEN_PRIMARY_X = 2, + MATAKEY_GREEN_PRIMARY_Y = 3, + MATAKEY_BLUE_PRIMARY_X = 4, + MATAKEY_BLUE_PRIMARY_Y = 5, + MATAKEY_WHITE_PRIMARY_X = 6, + MATAKEY_WHITE_PRIMARY_Y = 7, + MATAKEY_MAX_LUMINANCE = 8, + MATAKEY_MIN_LUMINANCE = 9, + MATAKEY_MAX_CONTENT_LIGHT_LEVEL = 10, + MATAKEY_MAX_FRAME_AVERAGE_LIGHT_LEVEL = 11, + MATAKEY_HDR10_PLUS = 12, + MATAKEY_HDR_VIVID = 13, +} HDRMetadataKey; + +/** + * @brief Defines the HDR metadata. + * + */ +typedef struct { + HDRMetadataKey key; + float value; +} HDRMetaData; + +/** + * @brief Defines information for verifying the memory to allocate. + * + */ +typedef struct { + uint32_t width; /**< Width of the memory to allocate */ + uint32_t height; /**< Height of the memory to allocate */ + uint64_t usage; /**< Usage of the memory */ + PixelFormat format; /**< Format of the memory to allocate */ +} VerifyAllocInfo; + +/** + * @brief Enumerates the present timestamp types. + * + */ +typedef enum { + HARDWARE_DISPLAY_PTS_UNSUPPORTED = 0, /**< Unsupported */ + HARDWARE_DISPLAY_PTS_DELAY = 1 << 0, /**< Delay */ + HARDWARE_DISPLAY_PTS_TIMESTAMP = 1 << 1, /**< Timestamp */ +} PresentTimestampType; + +/** + * @brief Defines the present timestamp. + * + */ +typedef struct { + PresentTimestampType type; /**< Present timestamp type */ + int64_t time; /**< Present timestamp value */ +} PresentTimestamp; + +#ifdef __cplusplus +} +#endif +#endif +/* @} */ diff --git a/en/device_api/hdi/display/display_vgu.h b/en/device_api/hdi/display/display_vgu.h new file mode 100644 index 0000000000000000000000000000000000000000..6214bfaa1aa0b88bd1c53d0eacf1d3f800585391 --- /dev/null +++ b/en/device_api/hdi/display/display_vgu.h @@ -0,0 +1,769 @@ +/* + * Copyright (c) 2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/* * + * @addtogroup Display + * @{ + * + * @brief Defines driver functions of the display module. + * + * This module provides driver functions for the graphics subsystem, including graphics layer management, + * device control, graphics hardware acceleration, display memory management, and callbacks. + * + * @since 3.0 + */ + +/* * + * @file display_vgu.h + * + * @brief Declares the driver functions for implementing 2D vector hardware acceleration. + * + * @since 3.0 + */ + +#ifndef DISPLAY_VGU_H +#define DISPLAY_VGU_H +#include "display_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +#undef HDI_VGU_SCALAR_IS_FLOAT +#define HDI_VGU_SCALAR_IS_FLOAT 1 + +#ifdef HDI_VGU_SCALAR_IS_FLOAT +typedef float VGUScalar; +#else +typedef int32_t VGUScalar; +#endif + +typedef PixelFormat VGUPixelFormat; /* < Pixel formats */ +typedef BlendType VGUBlendType; /* < Blend types supported by hardware acceleration */ + +/* * + * @brief Enumerates data types of paths. + * + */ +typedef enum { + VGU_DATA_TYPE_S16 = 0, /* < Integer (2 bytes) */ + VGU_DATA_TYPE_S32, /* < Integer (4 bytes) */ + VGU_DATA_TYPE_F32 /* < Floating point number (4 bytes) */ +} VGUPathDataType; + +/* * + * @brief Enumerates supported hardware acceleration capabilities. + * + */ +typedef enum { + VGU_CAP_BLIT = (1 << 0), /* < Bit blit */ + VGU_CAP_BLIT_NUM = (1 << 1), /* < Maximum number of images that can be combined during bit blit */ + VGU_CAP_PATH = (1 << 2), /* < Path filling and stroking */ + VGU_CAP_FILTER_BLUR = (1 << 3), /* < Blur filter */ +} VGUCapability; + +/* * + * @brief Enumerates result codes that may return. + * + */ +typedef enum { + VGU_SUCCESS = 0, /* < The operation is successful. */ + VGU_NO_SUPPORT = -1, /* < This feature is not supported. */ + VGU_OPERATION_FAILED = -2, /* < The operation failed. */ + VGU_OUT_OF_MEMORY = -3, /* < The operation ran out of memory. */ + VGU_TIMEOUT = -4, /* < The operation times out. */ + VGU_INVALID_PARAMETER = -5, /* < One or more parameters are invalid. */ + VGU_BUSY = -6, /* < The device is busy. */ + VGU_NO_CONTEXT = -7, /* < There is no context specified. */ +} VGUResult; + +/* * + * @brief Enumerates styles for the endpoints of a stroked line. + * + */ +typedef enum { + VGU_LINECAP_BUTT = 0, /* < A line with a squared-off end (default value) */ + VGU_LINECAP_ROUND, /* < A line with a rounded end */ + VGU_LINECAP_SQUARE /* < A line with a squared-off end */ +} VGULineCap; + +/* * + * @brief Enumerates join types for stroked lines. + * + */ +typedef enum { + VGU_LINE_JOIN_MITER = 0, /* < A join with a sharp corner (default value) */ + VGU_LINE_JOIN_ROUND, /* < A join with a rounded end */ + VGU_LINE_JOIN_BEVEL, /* < A join with a squared-off end */ + VGU_LINE_JOIN_BUTT /* < Invalid definition */ +} VGUJointType; + +/* * + * @brief Defines the coordinates of a point. + * + */ +typedef struct { + VGUScalar x; /* < Horizontal coordinate of the point */ + VGUScalar y; /* < Vertical coordinate of the point */ +} VGUPoint; + +/* * + * @brief Defines a rectangle. + * + */ +typedef struct { + VGUScalar x; /* < Horizontal coordinate of the start point of the rectangle */ + VGUScalar y; /* < Vertical coordinate of the start point of the rectangle */ + VGUScalar w; /* < Width of the rectangle */ + VGUScalar h; /* < Height of the rectangle */ +} VGURect; + +/* * + * @brief Enumerates filter types for rendering an image. + * + */ +typedef enum { + VGU_FILTER_BILINEAR = 0, /* < Bilinear interpolation filter (default value) */ + VGU_FILTER_NEAREST, /* < No interpolation filter */ + VGU_FILTER_LINEAR, /* < Linear interpolation filter */ + VGU_FILTER_BUTT /* < Invalid definition */ +} VGUFilter; + +/* * + * @brief Enumerates fill rules for graphics. + * + */ +typedef enum { + VGU_RULE_WINDING = 0, /* < Non-zero winding rule (default value) */ + VGU_RULE_EVEN_ODD, /* < Even-odd rule */ + VGU_RULE_BUTT /* < Invalid definition */ +} VGUFillRule; + +/* * + * @brief Enumerates fill types of the outside of the gradient area. + * + */ +typedef enum { + VGU_SPREAD_PAD = 0, /* < The area is filled with the closest gradient stop color. (Default value) */ + VGU_SPREAD_REFLECT, /* < The gradient is reflected outside the area. */ + VGU_SPREAD_REPEAT, /* < The gradient is repeated outside the area. */ + VGU_SPREAD_BUTT /* < Invalid definition */ +} VGUFillSpread; + +/* * + * @brief Enumerates wrap types of a pattern. + * + */ +typedef enum { + VGU_WRAP_REFLECT = 0, /* < The pattern is reflected. */ + VGU_WRAP_REPEAT, /* < The pattern is repeated. */ + VGU_WRAP_BUTT /* < Invalid definition */ +} VGUWrapType; + +/* * + * @brief Enumerates commands for drawing a path. + * + */ +typedef enum { + VGU_PATH_CMD_CLOSE = 0, /* < Close the current subpath (coordinates: none). */ + VGU_PATH_CMD_MOVE, /* < Move to the specified point (coordinates: x0, y0). */ + VGU_PATH_CMD_LINE, /* < Draw a line (coordinates: x0, y0). */ + VGU_PATH_CMD_HLINE, /* < Draw a horizontal line (coordinates: x0). */ + VGU_PATH_CMD_VLINE, /* < Draw a vertical line (coordinates: y0). */ + VGU_PATH_CMD_QUAD, /* < Draw a quadratic Bezier curve (coordinates: x0, y0, x1, y1). */ + VGU_PATH_CMD_CUBIC, /* < Draw a cubic Bezier curve (coordinates: x0, y0, x1, y1, x2, y2). */ + VGU_PATH_CMD_SQUAD, /* < Draw a smooth quadratic Bezier curve (coordinates: x1, y1). */ + VGU_PATH_CMD_SCUBIC, /* < Draw a smooth cubic Bezier curve (coordinates: x1, y1, x2, y2). */ + VGU_PATH_CMD_BUTT, /* < Invalid definition */ +} VGUPathCmd; + +/* * + * @brief Defines a path object, which stores path-related commands and coordinates. + * + */ +typedef struct { + uint8_t *segment; /* < Pointer to the path command data */ + int32_t numSegments; /* < Total number of path commands */ + uint8_t *data; /* < Pointer to the coordinates used in the path commands */ + VGUPathDataType type; /* < Data type of the path */ + bool enAlias; /* < Whether to enable anti-aliasing */ + VGURect boundBox; /* < Bounding box of the path */ +} VGUPath; + +/* * + * @brief Enumerates transform types. + * + */ +typedef enum { + VGU_TRANSFORM_TRANSLATE = (1 << 0), /* < Translate */ + VGU_TRANSFORM_SCALE = (1 << 1), /* < Scale */ + VGU_TRANSFORM_ROTATE_90 = (1 << 2), /* < Rotate by 90 degrees */ + VGU_TRANSFORM_ROTATE_180 = (1 << 3), /* < Rotate by 180 degrees */ + VGU_TRANSFORM_ROTATE_270 = (1 << 4), /* < Rotate by 270 degrees */ + VGU_TRANSFORM_OTHER = (1 << 16) /* < Other transform type */ +} VGUTransformType; + +/* * + * @brief Defines a transformation matrix. + * + */ +typedef struct { + float m[3][3]; /* < 3x3 transformation matrix */ + uint32_t type; /* < Transform type, which can be scale, translate, or rotate by 90 x N degrees */ +} VGUMatrix3; + +/* * + * @brief Stores bitmap information for hardware acceleration. + * + */ +typedef struct { + VGUPixelFormat pixelFormat; /* < Pixel format */ + uint32_t width; /* < Bitmap width */ + uint32_t height; /* < Bitmap height */ + uint32_t stride; /* < Bitmap stride */ + void *virAddr; /* < Virtual address of the requested memory */ + uint64_t phyAddr; /* < Physical memory address */ +} VGUBuffer; + +/* * + * @brief Enumerates clip types of a surface. + * + */ +typedef enum { + VGU_CLIP_RECT = 0, /* < Rectangle clip (default value) */ + VGU_CLIP_PATH, /* < Path clip */ + VGU_CLIP_BUTT /* < Invalid definition */ +} VGUClipType; + +/* * + * @brief Defines a mask layer. + * + */ +typedef struct { + VGUBuffer *buffer; /* < Pointer to the buffer for the mask */ + VGURect *rect; /* < Pointer to the rectangle for the mask */ +} VGUMaskLayer; + +/* * + * @brief Stores surface information for 2D hardware acceleration. + * + */ +typedef struct { + VGUBuffer *buffer; /* < Bitmap buffer */ + union { + VGURect *clipRect; /* < Pointer to the clip rectangle. If it is null, the entire surface will be rendered. */ + VGUPath *clipPath; /* < Pointer to the clip path. If it is null, the entire surface will be rendered. */ + }; + VGUClipType clipType; /* < Clip type of the surface */ + VGUMaskLayer *mask; /* < Mask layer, which can be null */ + VGUBlendType blend; /* < Blend type, specifying how a new image is drawn onto an existing surface */ + VGUFilter filter; /* < Filter type */ +} VGUSurface; + +/* * + * @brief Defines how the colors are distributed along the gradient. + * + */ +typedef struct { + float stop; /* < Stop position. The value ranges from 0.0 to 1.0. */ + uint32_t color; /* < Color of the stop */ +} VGUColorStop; + +/* * + * @brief Defines a linear gradient. + * + */ +typedef struct { + VGUScalar x1; /* < Horizontal coordinate of the start point of the linear gradient */ + VGUScalar y1; /* < Vertical coordinate of the start point of the linear gradient */ + VGUScalar x2; /* < Horizontal coordinate of the end point of the linear gradient */ + VGUScalar y2; /* < Vertical coordinate of the end point of the linear gradient */ +} VGULinear; + +/* * + * @brief Defines a radial gradient. + * + */ +typedef struct { + VGUScalar x0; /* < Horizontal coordinate of the center of the inner circle */ + VGUScalar y0; /* < Vertical coordinate of the center of the inner circle */ + VGUScalar r0; /* < Radius of the inner circle */ + VGUScalar x1; /* < Horizontal coordinate of the center of the outer circle */ + VGUScalar y1; /* < Vertical coordinate of the center of the outer circle */ + VGUScalar r1; /* < Radius of the outer circle */ +} VGURadial; + +/* * + * @brief Defines a conic gradient. + * + */ +typedef struct { + VGUScalar cx; /* < Horizontal coordinate of the center of the circle */ + VGUScalar cy; /* < Vertical coordinate of the center of the circle */ +} VGUConic; + +/* * + * @brief Defines an image. + * + */ +typedef struct { + VGUBuffer *buffer; /* < Image buffer */ + VGUMatrix3 *matrix; /* < Pointer to the transformation matrix. If it is null, the identity matrix is used. */ + VGURect *rect; /* < Pointer to the rectangle of the image. If it is null, the entire buffer data is used. */ + uint8_t opacity; /* < Opacity. The value ranges from 0 to 255. */ +} VGUImage; + +/* * + * @brief Defines an image pattern. + * + */ +typedef struct { + VGUImage *image; /* < Pointer to the image object */ + VGUWrapType wrapx; /* < Wrap the image horizontally. */ + VGUWrapType wrapy; /* < Wrap the image vertically. */ +} VGUPattern; + +/* * + * @brief Enumerates gradient types. + * + */ +typedef enum { + VGU_GRADIENT_LINEAR = 0, /* < Linear gradient */ + VGU_GRADIENT_RADIAL, /* < Radial gradient */ + VGU_GRADIENT_CONIC, /* < Conic gradient */ + VGU_GRADIENT_BUTT /* < Invalid definition */ +} VGUGradientType; + +/* * + * @brief Defines a gradient object. + * + */ +typedef struct { + VGUMatrix3 *matrix; /* < Pointer to the transformation matrix of the gradient object */ + VGUColorStop *colorStops; /* < Pointer to the gradient stop color array */ + uint16_t stopCount; /* < Number of stop colors */ + union { + VGULinear linear; /* < Linear gradient object */ + VGURadial radial; /* < Radial gradient object */ + VGUConic conic; /* < Conic gradient object */ + }; + VGUGradientType type; /* < Gradient type */ + VGUFillSpread spread; /* < Gradient spread mode */ + uint8_t opacity; /* < Opacity. The value ranges from 0 to 255. */ +} VGUGradient; + +/* * + * @brief Defines a solid color. + * + */ +typedef struct { + uint32_t color; /* < Solid color */ + uint8_t opacity; /* < Opacity. The value ranges from 0 to 255. */ +} VGUSolid; + +/* * + * @brief Enumerates paint types. + * + */ +typedef enum { + VGU_PAINT_SOLID = 0, /* < Paint a solid color. */ + VGU_PAINT_GRADIENT, /* < Paint a gradient object. */ + VGU_PAINT_PATTERN, /* < Paint a pattern. */ + VGU_PAINT_BUTT /* < Invalid operation */ +} VGUPaintType; + +/* * + * @brief Defines the paint style when filling or stroking a path. + * + */ +typedef struct { + union { + VGUGradient *gradient; /* < Pointer to the gradient object */ + VGUPattern *pattern; /* < Pointer to the pattern object */ + VGUSolid *solid; /* < Pointer to the solid color object */ + }; + VGUPaintType type; /* < Paint type */ +} VGUPaintStyle; + +/* * + * @brief Defines path filling attributes. + * + */ +typedef struct { + VGUFillRule rule; /* < Fill rule */ +} VGUFillAttr; + +/* * + * @brief Defines path stroking attributes. + * + */ +typedef struct { + VGULineCap cap; /* < Line cap style */ + VGUJointType join; /* < Join type */ + float miterLimit; /* < Miter limit */ + float width; /* < Line width */ +} VGUStrokeAttr; + +/* * + * @brief Defines driver functions for 2D hardware acceleration. + */ +typedef struct { + /* * + * @brief Initializes hardware acceleration. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @see DeinitVgu + * @since 3.0 + */ + VGUResult (*InitVgu)(void); + + /* * + * @brief Deinitializes hardware acceleration. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @see InitVgu + * @since 3.0 + */ + VGUResult (*DeinitVgu)(void); + + /* * + * @brief Queries hardware acceleration capabilities. + * + * @param cap Indicates the capabilities to query, which are defined by VGUCapability. + * + * @return Returns a value greater than or equal to 0 if the operation is successful; returns an error code defined + * in {@link VGUResult} otherwise. + * @since 3.0 + */ + int32_t (*QueryCapability)(uint32_t cap); + + /* * + * @brief Fills the given path with a specified paint style. + * + * @param target Indicates the pointer to the target surface. + * @param path Indicates the pointer to the path object. + * @param matrix Indicates the pointer to the transformation matrix object. If this parameter is null, + * the identity matrix is used by default. + * @param attr Indicates the pointer to the path filling attributes. + * @param style Indicates the pointer to the paint style to use. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ + VGUResult (*RenderFill)(VGUSurface *target, const VGUPath *path, const VGUMatrix3 *matrix, const VGUFillAttr *attr, + const VGUPaintStyle *style); + + /* * + * @brief Strokes the given path with a specified paint style. + * + * @param target Indicates the pointer to the target surface. + * @param path Indicates the pointer to the path object. + * @param matrix Indicates the pointer to the transformation matrix object. If this parameter is null, + * the identity matrix is used by default. + * @param attr Indicates the pointer to the path stroking attributes. + * @param style Indicates the pointer to the paint style to use. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ + VGUResult (*RenderStroke)(VGUSurface *target, const VGUPath *path, const VGUMatrix3 *matrix, + const VGUStrokeAttr *attr, const VGUPaintStyle *style); + + /* * + * @brief Blurs a specified surface. + * + * @param target Indicates the pointer to the target surface. + * @param blur Indicates the blur radius. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ + VGUResult (*RenderBlur)(VGUSurface *target, uint16_t blur); + + /* * + * @brief Blits an image to the target surface. + * + * During bit blit, color space conversion (CSC) and transformation can be implemented. + * + * @param target Indicates the pointer to the target surface. + * @param src Indicates the pointer to the source image. + * @param color Indicates the color for blending. If this parameter is 0, color blending is not performed. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ + VGUResult (*RenderBlit)(VGUSurface *target, const VGUImage *src, uint32_t color); + + /* * + * @brief Blits multiple images to the target surface. + * + * During bit blit, color space conversion (CSC) and transformation can be implemented. You can use this + * function to combine multiple source images to the target surface. + * To query the maximum number of source images allowed, call the QueryCapability function. + * + * @param target Indicates the pointer to the target surface. + * @param src Indicates the pointer to the array of source images. + * @param count Indicates the number of source images. + * @param color Indicates the color for blending. If this parameter is 0, color blending is not performed. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ + VGUResult (*RenderBlitN)(VGUSurface *target, const VGUImage *src, uint16_t count, uint32_t color); + + /* * + * @brief Clears a rectangle with a given color on the target surface. + * + * @param target Indicates the pointer to the target surface. + * @param rect Indicates the pointer to the rectangle to clear. If this parameter is null, the entire surface + * will be cleared. + * @param color Indicates the color to fill. + * @param opacity Indicates the opacity to set. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ + VGUResult (*RenderClearRect)(VGUSurface *target, const VGURect *rect, uint32_t color, uint8_t opacity); + + /* * + * @brief Disables hardware acceleration for rendering. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ + VGUResult (*RenderCancel)(); + + /* * + * @brief Synchronizes hardware acceleration when it is used to draw and blit bitmaps. + * + * This function blocks the process until hardware acceleration is complete. + * + * @param timeOut Indicates the timeout duration for hardware acceleration synchronization. + * The value 0 indicates no timeout, so the process keeps waiting until hardware acceleration is complete. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ + VGUResult (*RenderSync)(int32_t timeOut); +} VGUFuncs; + +/* * + * @brief Initializes a path object. + * + * @param path Indicates the pointer to the path object. + * @param type Indicates the data type of the path. + * @param segments Indicates the pointer to the path commands. + * @param numSegments Indicates the total number of path commands. + * @param data Indicates the pointer to the coordinate data used in the path commands. + * @param enAlias Specifies whether to enable anti-aliasing. + * @param boundBox Indicates the bounding box of the path. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUPathInit(VGUPath *path, VGUPathDataType type, const uint8_t* segments, int numSegments, + const uint8_t *data, bool enAlias, VGURect boundBox); + +/* * + * @brief Adds a subpath to a specified path. + * + * @param path Indicates the pointer to the path object. + * @param subpath Indicates the pointer to the subpath object. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUPathAppend(VGUPath *path, const VGUPath *subpath); + +/* * + * @brief Clears the memory of a specified path object. + * + * @param path Indicates the pointer to the path object. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUPathClear(VGUPath *path); + +/* * + * @brief Loads an identity matrix into a specified matrix object. + * + * @param matrix Indicates the pointer to the transformation matrix object. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUMatrixIdentity(VGUMatrix3 *matrix); + +/* * + * @brief Scales a specified transformation matrix. + * + * @param matrix Indicates the pointer to the transformation matrix object. + * @param xScale Indicates how much you want to scale the horizontal coordinate by. + * @param yScale Indicates how much you want to scale the vertical coordinate by. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUMatrixScale(VGUMatrix3 *matrix, float xScale, float yScale); + +/* * + * @brief Rotates a specified transformation matrix. + * + * @param matrix Indicates the pointer to the transformation matrix object. + * @param degree Indicates the number of degrees to rotate. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUMatrixRotate(VGUMatrix3 *matrix, float degree); + +/* * + * @brief Translates a specified transformation matrix. + * + * @param matrix Indicates the pointer to the transformation matrix object. + * @param x Indicates how much you want to translate the horizontal coordinate by. + * @param y Indicates how much you want to translate the vertical coordinate by. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUMatrixTranslate(VGUMatrix3 *matrix, float x, float y); + +/* * + * @brief Adds color stops to a specified gradient. + * + * @param gradient Indicates the pointer to the gradient object. + * @param colorStop Indicates the pointer to the color stop array. + * @param count Indicates the total number of color stops. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUGradientColorStop(VGUGradient *gradient, const VGUColorStop *colorStop, uint32_t count); + +/* * + * @brief Clears color stops of a specified gradient. + * + * @param gradient Indicates the pointer to the gradient object. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUGradientClearStop(VGUGradient *gradient); + +/* * + * @brief Sets a transformation matrix for a specified gradient. + * + * @param gradient Indicates the pointer to the gradient object. + * @param matrix Indicates the pointer to the transformation matrix object to set. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUGradientMatrix(VGUGradient *gradient, const VGUMatrix3 *matrix); + +/* * + * @brief Creates a linear gradient object. + * + * @param gradient Indicates the pointer to the gradient object. + * @param p1 Indicates the pointer to the coordinates of the start point. + * @param p2 Indicates the pointer to the coordinates of the end point. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUGradientLinear(VGUGradient *gradient, const VGUPoint *p1, const VGUPoint *p2); + +/* * + * @brief Creates a radial gradient object. + * + * @param gradient Indicates the pointer to the gradient object. + * @param p1 Indicates the pointer to the center point coordinates of the inner circle. + * @param r1 Indicates the radius of the inner circle. + * @param p2 Indicates the pointer to the center point coordinates of the outer circle. + * @param r2 Indicates the radius of the outer circle. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUGradientRadial(VGUGradient *gradient, const VGUPoint *p1, VGUScalar r1, const VGUPoint *p2, VGUScalar r2); + +/* * + * @brief Creates a conic gradient object. + * + * @param gradient Indicates the pointer to the gradient object. + * @param cx Indicates the horizontal coordinate of the center point of the gradient. + * @param cy Indicates the vertical coordinate of the center point of the gradient. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUGradientConic(VGUGradient *gradient, VGUScalar cx, VGUScalar cy); + +/* * + * @brief Initializes the hardware acceleration module to obtain the pointer to functions for + * hardware acceleration operations. + * + * @param funcs Indicates the double pointer to the functions for hardware acceleration operations. + * Memory is allocated automatically when you initiate the hardware acceleration module, so you can simply use + * the pointer to gain access to the functions. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * + * @since 3.0 + */ +VGUResult VGUInitialize(VGUFuncs **funcs); + +/* * + * @brief Deinitializes the hardware acceleration module to release the pointer to functions + * for hardware acceleration operations. + * + * @param funcs Indicates the pointer to the functions for hardware acceleration operations. + * + * @return Returns VGU_SUCCESS if the operation is successful; returns an error code defined in + * {@link VGUResult} otherwise. + * @since 3.0 + */ +VGUResult VGUUninitialize(VGUFuncs *funcs); + +#ifdef __cplusplus +} +#endif +#endif diff --git a/en/device_api/hdi/input/input_controller.h b/en/device_api/hdi/input/input_controller.h new file mode 100644 index 0000000000000000000000000000000000000000..7bc4321c7617f66123043a9ecbad5c65c209d0fd --- /dev/null +++ b/en/device_api/hdi/input/input_controller.h @@ -0,0 +1,203 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Input + * @{ + * + * @brief Provides driver interfaces for the input service. + * + * These driver interfaces can be used to open and close input device files, get input events, query device information, + * register callback functions, and control the feature status. + * + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file input_controller.h + * + * @brief Declares the driver interfaces for controlling the business process of input devices. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef INPUT_CONTROLLER_H +#define INPUT_CONTROLLER_H + +#include "input_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Provides interfaces for controlling the business process of input devices. + * + * The interfaces can be called to set the power status, enable or disable a feature, get driver chip information, + * and control the production test. + */ +typedef struct { + /** + * @brief Sets the power status. + * + * This function is called only when the power status of the OS is changed. \n + * The input service or the power management module can call this function to set the power status + * for the input device when the OS is in the Resume or Suspend status, so that the driver integrated circuit (IC) + * of the device can normally enter the specified status. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param status Indicates the power status to set. The input service will notify the input device of entering the + * Resume or Suspend state specified by {@link PowerStatus}. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetPowerStatus)(uint32_t devIndex, uint32_t status); + + /** + * @brief Gets the power status. + * + * The input service or the power management module can get the power status for the input device when the OS + * is in the Resume or Suspend status, so that the driver IC of the device can normally enter the specified status. + * You can call this function to obtain the power status. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param status Indicates the pointer to the power status of the device. For details, see {@link PowerStatus}. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetPowerStatus)(uint32_t devIndex, uint32_t *status); + + /** + * @brief Gets the type of the input device based on the specified device index. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param deviceType Indicates the pointer to the device type. For details, see {@link InputDevType}. + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetDeviceType)(uint32_t devIndex, uint32_t *deviceType); + + /** + * @brief Gets the chip information of the specified device. + * + * A product is usually equipped with modules and driver ICs provided by multiple vendors. An input service + * can call this function to get the specific information if needed. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param chipInfo Indicates the pointer to the chip information. + * @param length Indicates the length of the chip information. The minimum value of length is 10. + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetChipInfo)(uint32_t devIndex, char *chipInfo, uint32_t length); + + /** + * @brief Gets the module vendor name of the specified device. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param vendorName Indicates the pointer to the module vendor name. + * @param length Indicates the length of the module vendor name. The minimum value of length is 10. + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetVendorName)(uint32_t devIndex, char *vendorName, uint32_t length); + + /** + * @brief Gets the driver chip name of the specified device. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param chipName Indicates the pointer to the driver chip name. + * @param length Indicates the length of the driver chip name. The minimum value of length is 10. + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetChipName)(uint32_t devIndex, char *chipName, uint32_t length); + + /** + * @brief Sets the gesture mode. + * + * The input service can use this function to enable or disable the gesture mode by setting EnableBit + * of the gesture mode. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param gestureMode Indicates the gesture mode to set. + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*SetGestureMode)(uint32_t devIndex, uint32_t gestureMode); + + /** + * @brief Conducts a capacitance self-test. + * + * The capacitance self-test items are defined by the component vendor, such as the tests on the raw data, + * short circuit, open circuit, interference, and row/column difference. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param testType Indicates the capacitance test type. For details, see {@link CapacitanceTest}. + * @param result Indicates the pointer to the capacitance test result. The value is SUCC for a successful + * operation and is an error code for a failed operation. + * @param length Indicates the length of the test result. The minimum value of length is 20. + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*RunCapacitanceTest)(uint32_t devIndex, uint32_t testType, char *result, uint32_t length); + + /** + * @brief Executes the extra command. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param cmd Indicates the pointer to the extra command data packet, including the command codes and parameters. + * For details, see {@link InputExtraCmd}. + * @return Returns 0 if the operation is successful; returns an error code defined + * in {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*RunExtraCommand)(uint32_t devIndex, InputExtraCmd *cmd); +} InputController; + +#ifdef __cplusplus +} +#endif +#endif +/** @} */ diff --git a/en/device_api/hdi/input/input_manager.h b/en/device_api/hdi/input/input_manager.h new file mode 100644 index 0000000000000000000000000000000000000000..1ec106b0a40d29531ea139e40adb6670f05f11c6 --- /dev/null +++ b/en/device_api/hdi/input/input_manager.h @@ -0,0 +1,158 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Input + * @{ + * + * @brief Provides driver interfaces for the input service. + * + * These driver interfaces can be used to open and close input device files, get input events, query device information, + * register callback functions, and control the feature status. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file input_manager.h + * + * @brief Declares the driver interfaces for managing input devices. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef INPUT_MANAGER_H +#define INPUT_MANAGER_H + +#include "input_controller.h" +#include "input_reporter.h" +#include "input_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Provides interfaces for managing input devices. + * + * The interfaces can be used to perform basic operations on the input devices, such as scanning online devices, + * opening and closing the device files, querying information about a specified input device, and obtaining information + * about all input devices in the device list. + */ +typedef struct { + /** + * @brief Scans all online input devices. + * + * @param staArr Indicates the pointer to the array storing information about the scanned input devices, + * including the device index and device type. + * @param arrLen Indicates the length of the array. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*ScanInputDevice)(InputDevDesc *staArr, uint32_t arrLen); + + /** + * @brief Opens a specified input device file. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*OpenInputDevice)(uint32_t devIndex); + + /** + * @brief Closes a specified input device file. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*CloseInputDevice)(uint32_t devIndex); + + /** + * @brief Gets information about a specified input device. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param devInfo Indicates the double pointer to information about the specified device. + * For details, see {@link DeviceInfo}. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetInputDevice)(uint32_t devIndex, InputDeviceInfo **devInfo); + + /** + * @brief Gets information about all input devices in the device list. + * + * @param devNum Indicates the pointer to the total number of input devices which have been registered. + * @param devList Indicates the double pointer to information about all devices in the device list. + * For details, see {@link DeviceInfo}. + * @param size Indicates the number of elements in the devList array. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*GetInputDeviceList)(uint32_t *devNum, InputDeviceInfo **devList, uint32_t size); +} InputManager; + +/** + * @brief Defines interfaces for providing driver capabilities of input devices. + */ +typedef struct { + InputManager *iInputManager; /**< Device management interface for input devices */ + InputController *iInputController; /**< Service control interface for input devices */ + InputReporter *iInputReporter; /**< Data reporting interface for input devices */ +} IInputInterface; + +/** + * @brief Gets all interfaces for performing operations on input devices. + * + * @param interface Indicates the double pointer to the interfaces for performing operations on input devices. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ +int32_t GetInputInterface(IInputInterface **interface); + +/** + * @brief Releases all interfaces for performing operations on input devices. + * + * @param inputInterface Indicates the pointer to the interfaces for performing operations on input devices. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ +void ReleaseInputInterface(IInputInterface *inputInterface); + +#ifdef __cplusplus +} +#endif +#endif +/** @} */ diff --git a/en/device_api/hdi/input/input_reporter.h b/en/device_api/hdi/input/input_reporter.h new file mode 100644 index 0000000000000000000000000000000000000000..b73b65ebb02ca151ab46890d0d966025b24d810d --- /dev/null +++ b/en/device_api/hdi/input/input_reporter.h @@ -0,0 +1,110 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup Input + * @{ + * + * @brief Provides driver interfaces for the input service. + * + * These driver interfaces can be used to open and close input device files, get input events, query device information, + * register callback functions, and control the feature status. + * + * @since 1.0 + * @version 1.0 + */ + +/** + * @file input_reporter.h + * + * @brief Declares the driver interfaces for reporting data of input devices. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef INPUT_REPORTER_H +#define INPUT_REPORTER_H + +#include "input_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Provides interfaces for reporting event data of input devices. + * + * The interfaces include the registration and unregistration of callbacks for reporting subscribed data of specified + * input devices. + */ +typedef struct { + /** + * @brief Registers a callback for reporting subscribed data of specified input devices. + * + * After this callback is successfully registered, the driver can report the input event data to the input service + * through this callback. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @param callback Indicates the pointer to the callback to register. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*RegisterReportCallback)(uint32_t devIndex, InputEventCb *callback); + + /** + * @brief Unregisters the callback for reporting subscribed data of specified input devices. + * + * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported. + * The value ranges from 0 to 31, and value 0 represents the first input device. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*UnregisterReportCallback)(uint32_t devIndex); + + /** + * @brief Registers a hot plug callback to the HDIs for input devices. + * + * All input devices can use this callback to report hot plug events. + * + * @param callback Indicates the pointer to the callback to register. + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*RegisterHotPlugCallback)(InputHostCb *callback); + + /** + * @brief Unregisters the hot plug callback of input devices. + * + * @return Returns 0 if the operation is successful; returns an error code defined in + * {@link RetStatus} otherwise. + * @since 1.0 + * @version 1.0 + */ + int32_t (*UnregisterHotPlugCallback)(void); +} InputReporter; + +#ifdef __cplusplus +} +#endif +#endif +/** @} */ diff --git a/en/device_api/hdi/input/input_type.h b/en/device_api/hdi/input/input_type.h new file mode 100644 index 0000000000000000000000000000000000000000..57072ba49b86b7ea5571a2dfe043a5fcda28152a --- /dev/null +++ b/en/device_api/hdi/input/input_type.h @@ -0,0 +1,230 @@ +/* + * Copyright (c) 2020-2021 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + /** + * @addtogroup Input + * @{ + * + * @brief Provides driver interfaces for the input service. + * + * These driver interfaces can be used to open and close input device files, get input events, query device information, + * register callback functions, and control the feature status. + * + * @since 1.0 + * @version 1.0 + */ + + /** + * @file input_type.h + * + * @brief Declares types of input devices as well as the structure and enumeration types used by driver interfaces. + * + * @since 1.0 + * @version 1.0 + */ + +#ifndef INPUT_TYPES_H +#define INPUT_TYPES_H + +#include +#include +#include + +#ifndef _UAPI_INPUT_H +#include +#endif + +#ifdef __cplusplus +extern "C" { +#endif + +#define MAX_INPUT_DEV_NUM 32 +#define CHIP_INFO_LEN 10 +#define CHIP_NAME_LEN 10 +#define VENDOR_NAME_LEN 10 +#define DEV_NAME_LEN 64 +#define SELF_TEST_RESULT_LEN 20 +#define DEV_MANAGER_SERVICE_NAME "hdf_input_host" +#ifdef DIV_ROUND_UP +#undef DIV_ROUND_UP +#endif +#define DIV_ROUND_UP(nr, d) (((nr) + (d) - 1) / (d)) +#define BYTE_HAS_BITS 8 +#define BITS_TO_UINT64(count) DIV_ROUND_UP(count, BYTE_HAS_BITS * sizeof(uint64_t)) +#define HDF_FF_CNT (0x7f + 1) +/** + * @brief Enumerates return values. + */ +enum RetStatus { + INPUT_SUCCESS = 0, /**< Success */ + INPUT_FAILURE = -1, /**< Failure */ + INPUT_INVALID_PARAM = -2, /**< Invalid parameter */ + INPUT_NOMEM = -3, /**< Insufficient memory */ + INPUT_NULL_PTR = -4, /**< Null pointer */ + INPUT_TIMEOUT = -5, /**< Execution timed out */ + INPUT_UNSUPPORTED = -6, /**< Unsupported feature */ +}; + +/** + * @brief Enumerates input device types. + */ +enum InputDevType { + INDEV_TYPE_TOUCH, /**< Touchscreen */ + INDEV_TYPE_KEY, /**< Physical key */ + INDEV_TYPE_BUTTON, /**< Virtual button */ + INDEV_TYPE_CROWN, /**< Watch crown */ + INDEV_TYPE_HID_BEGIN_POS = 33, /**< HID type start position */ + INDEV_TYPE_ENCODER, /**< Encoder */ + INDEV_TYPE_MOUSE, /**< Mouse */ + INDEV_TYPE_KEYBOARD, /**< Keyboard */ + INDEV_TYPE_ROCKER, /**< ROCKER */ + INDEV_TYPE_TRACKBALL, /**< TRACKBALL */ + INDEV_TYPE_UNKNOWN, /**< Unknown input device type */ +}; + +/** + * @brief Enumerates power statuses. + */ +enum PowerStatus { + INPUT_RESUME, /**< Resume status */ + INPUT_SUSPEND, /**< Suspend status */ + INPUT_LOW_POWER, /**< Low-power status */ + INPUT_POWER_STATUS_UNKNOWN, /**< Unknown power status */ +}; + +/** + * @brief Enumerates types of capacitance tests. + */ +enum CapacitanceTest { + BASE_TEST, /**< Basic capacitance test */ + FULL_TEST, /**< Full capacitance self-test */ + MMI_TEST, /**< Man-Machine Interface (MMI) capacitance test */ + RUNNING_TEST, /**< Running capacitance test */ + TEST_TYPE_UNKNOWN, /**< Unknown test type */ +}; + +/** + * @brief Describes the input event data package. + */ +typedef struct { + uint32_t type; /**< Type of the input event */ + uint32_t code; /**< Specific code item of the input event */ + int32_t value; /**< Value of the input event code item */ + uint64_t timestamp; /**< Timestamp of the input event */ +} InputEventPackage; + +typedef struct { + uint32_t devIndex; + uint32_t devType; + uint32_t status; +} InputHotPlugEvent; + +typedef struct { + uint32_t devIndex; + uint32_t devType; +} InputDevDesc; + +/** + * @brief Describes the input event callback registered by the input service. + */ +typedef struct { + /** + * @brief Reports input event data by the registered callback. + * + * @param pkgs describes the input event data package. + * @param count Indicates the number of input event data packets. + * @param devIndex Indicates the index of an input device. + * @since 1.0 + * @version 1.0 + */ + void (*EventPkgCallback)(const InputEventPackage **pkgs, uint32_t count, uint32_t devIndex); +} InputEventCb; + +typedef struct { + /** + * @brief Reports hot plug event data by the registered callback. + * + * @param event Indicates the pointer to the hot plug event data reported by the input driver. + * @since 1.0 + * @version 1.0 + */ + void (*HotPlugCallback)(const InputHotPlugEvent *event); +} InputHostCb; + +typedef struct { + uint64_t devProp[BITS_TO_UINT64(INPUT_PROP_CNT)]; + uint64_t eventType[BITS_TO_UINT64(EV_CNT)]; + uint64_t absCode[BITS_TO_UINT64(ABS_CNT)]; + uint64_t relCode[BITS_TO_UINT64(REL_CNT)]; + uint64_t keyCode[BITS_TO_UINT64(KEY_CNT)]; + uint64_t ledCode[BITS_TO_UINT64(LED_CNT)]; + uint64_t miscCode[BITS_TO_UINT64(MSC_CNT)]; + uint64_t soundCode[BITS_TO_UINT64(SND_CNT)]; + uint64_t forceCode[BITS_TO_UINT64(HDF_FF_CNT)]; + uint64_t switchCode[BITS_TO_UINT64(SW_CNT)]; + uint64_t keyType[BITS_TO_UINT64(KEY_CNT)]; + uint64_t ledType[BITS_TO_UINT64(LED_CNT)]; + uint64_t soundType[BITS_TO_UINT64(SND_CNT)]; + uint64_t switchType[BITS_TO_UINT64(SW_CNT)]; +} InputDevAbility; + +typedef struct { + int32_t axis; + int32_t min; + int32_t max; + int32_t fuzz; + int32_t flat; + int32_t range; +} InputDimensionInfo; + +typedef struct { + uint16_t busType; + uint16_t vendor; + uint16_t product; + uint16_t version; +} InputDevIdentify; + +typedef struct { + char devName[DEV_NAME_LEN]; + InputDevIdentify id; + InputDimensionInfo axisInfo[ABS_CNT]; +} InputDevAttr; + +/** + * @brief Describes basic device information of the input device. + */ +typedef struct { + uint32_t devIndex; /**< Device index */ + uint32_t devType; /**< Device type */ + char chipInfo[CHIP_INFO_LEN]; /**< Driver chip information */ + char vendorName[VENDOR_NAME_LEN]; /**< Module vendor name */ + char chipName[CHIP_NAME_LEN]; /**< Driver chip name */ + InputDevAttr attrSet; + InputDevAbility abilitySet; +} InputDeviceInfo; + +/** + * @brief Describes the extra commands. + */ +typedef struct { + const char *cmdCode; /**< Command code */ + const char *cmdValue; /**< Data transmitted in the command */ +} InputExtraCmd; + +#ifdef __cplusplus +} +#endif +#endif +/** @} */