/* * Copyright (c) 2022 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 OH_NativeImage * @{ * * @brief Provides the native image capability. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @since 9 * @version 1.0 */ /** * @file native_image.h * * @brief Defines the functions for obtaining and using a native image. * * @library libnative_image.so * @since 9 * @version 1.0 */ #ifndef NDK_INCLUDE_NATIVE_IMAGE_H_ #define NDK_INCLUDE_NATIVE_IMAGE_H_ #include #ifdef __cplusplus extern "C" { #endif struct OH_NativeImage; typedef struct OH_NativeImage OH_NativeImage; typedef struct NativeWindow OHNativeWindow; /** * @brief define the new type name OHNativeWindowBuffer for struct NativeWindowBuffer. * @since 12 */ typedef struct NativeWindowBuffer OHNativeWindowBuffer; /** * @brief The callback function of frame available. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param context User defined context, returned to the user in the callback function * @since 11 * @version 1.0 */ typedef void (*OH_OnFrameAvailable)(void *context); /** * @brief A listener for native image, use OH_NativeImage_SetOnFrameAvailableListener to register \n * the listener object to OH_NativeImage, the callback will be triggered when there is available frame * * @since 11 * @version 1.0 */ typedef struct OH_OnFrameAvailableListener { void *context; OH_OnFrameAvailable onFrameAvailable; } OH_OnFrameAvailableListener; /** * @brief Create a OH_NativeImage related to an Opengl ES texture and target. \n * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param textureId Indicates the id of the Opengl ES texture which the native image attached to. * @param textureTarget Indicates the Opengl ES target. * @return Returns the pointer to the OH_NativeImage instance created if the operation is successful, \n * returns NULL otherwise. * @since 9 * @version 1.0 */ OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget); /** * @brief Acquire the OHNativeWindow for the OH_NativeImage. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @return Returns the pointer to the OHNativeWindow if the operation is successful, returns NULL otherwise. * @since 9 * @version 1.0 */ OHNativeWindow* OH_NativeImage_AcquireNativeWindow(OH_NativeImage* image); /** * @brief Attach the OH_NativeImage to Opengl ES context, and the Opengl ES texture is bound to the \n * GL_TEXTURE_EXTERNAL_OES, which will update by the OH_NativeImage. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param textureId Indicates the id of the Opengl ES texture which the native image attached to. * @return Returns an error code, 0 is success, otherwise, failed. * @since 9 * @version 1.0 */ int32_t OH_NativeImage_AttachContext(OH_NativeImage* image, uint32_t textureId); /** * @brief Detach the OH_NativeImage from the Opengl ES context. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @return Returns an error code, 0 is success, otherwise, failed. * @since 9 * @version 1.0 */ int32_t OH_NativeImage_DetachContext(OH_NativeImage* image); /** * @brief Update the related Opengl ES texture with the OH_NativeImage acquired buffer. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @return Returns an error code, 0 is success, otherwise, failed. * @since 9 * @version 1.0 */ int32_t OH_NativeImage_UpdateSurfaceImage(OH_NativeImage* image); /** * @brief Get the timestamp of the texture image set by the most recent call to OH_NativeImage_UpdateSurfaceImage. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @return Returns the timestamp associated to the texture image. * @since 9 * @version 1.0 */ int64_t OH_NativeImage_GetTimestamp(OH_NativeImage* image); /** * @brief Obtains the transform matrix of the texture image set by the most recent call to \n * OH_NativeImage_UpdateSurfaceImage. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param matrix Indicates the retrieved 4*4 transform matrix . * @return Returns an error code, 0 is success, otherwise, failed. * @since 9 * @version 1.0 * @deprecated since 12 * @useinstead OH_NativeImage_GetTransformMatrixV2 */ int32_t OH_NativeImage_GetTransformMatrix(OH_NativeImage* image, float matrix[16]); /** * @brief Obtains the native image's surface id. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param surfaceId Indicates the surface id. * @return Returns an error code, 0 is success, otherwise, failed. * @since 11 * @version 1.0 */ int32_t OH_NativeImage_GetSurfaceId(OH_NativeImage* image, uint64_t* surfaceId); /** * @brief Set the frame available callback. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param listener Indicates the callback function. * @return Returns an error code, 0 is success, otherwise, failed. * @since 11 * @version 1.0 */ int32_t OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage* image, OH_OnFrameAvailableListener listener); /** * @brief Unset the frame available callback. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @return Returns an error code, 0 is success, otherwise, failed. * @since 11 * @version 1.0 */ int32_t OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage* image); /** * @brief Destroy the OH_NativeImage created by OH_NativeImage_Create, and the pointer to \n * OH_NativeImage will be null after this operation. * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage pointer. * @since 9 * @version 1.0 */ void OH_NativeImage_Destroy(OH_NativeImage** image); /** * @brief Obtains the transform matrix of the texture image by producer transform type.\n * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param matrix Indicates the retrieved 4*4 transform matrix . * @return 0 - Success. * 40001000 - image is NULL. * @since 12 * @version 1.0 */ int32_t OH_NativeImage_GetTransformMatrixV2(OH_NativeImage* image, float matrix[16]); /** * @brief Acquire an OHNativeWindowBuffer through an OH_NativeImage instance for content consumer.\n * This method can not be used at the same time with OH_NativeImage_UpdateSurfaceImage.\n * This method will create an OHNativeWindowBuffer.\n * If there is a situation when OHNativeWindowBuffer is still used after calling * OH_NativeImage_ReleaseNativeWindowBuffer, you must pay attention to the following two points.\n * 1) When using OHNativeWindowBuffer, need to increase its reference count * by OH_NativeWindow_NativeObjectReference.\n * 2) When the OHNativeWindowBuffer is used up, its reference count needs to be decremented * by OH_NativeWindow_NativeObjectUnreference.\n * This interface needs to be used in conjunction with OH_NativeImage_ReleaseNativeWindowBuffer<\b>, * otherwise memory leaks will occur.\n * When the fenceFd is used up, you need to close it.\n * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param nativeWindowBuffer Indicates the pointer to an OHNativeWindowBuffer point. * @param fenceFd Indicates the pointer to a file descriptor handle. * @return {@link NATIVE_ERROR_OK} 0 - Success. * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer, fenceFd is NULL. * {@link NATIVE_ERROR_NO_BUFFER} 40601000 - No buffer for consume. * @since 12 * @version 1.0 */ int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image, OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd); /** * @brief Release the OHNativeWindowBuffer to the buffer queue through an * OH_NativeImage instance for reuse.\n * The fenceFd will be close by system.\n * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param nativeWindowBuffer Indicates the pointer to an OHNativeWindowBuffer instance. * @param fenceFd Indicates a file descriptor handle, which is used for timing synchronization. * @return {@link NATIVE_ERROR_OK} 0 - Success. * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer is NULL. * {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - nativeWindowBuffer state invalid. * {@link NATIVE_ERROR_BUFFER_NOT_IN_CACHE} 41210000 - nativeWindowBuffer not in cache. * @since 12 * @version 1.0 */ int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image, OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd); /** * @brief Create a OH_NativeImage as surface consumer. \n * This method can not be used at the same time with OH_NativeImage_UpdateSurfaceImage.\n * This interface needs to be used in conjunction with OH_NativeImage_Destroy<\b>, * otherwise memory leaks will occur.\n * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @return Returns the pointer to the OH_NativeImage instance created if the operation is successful, \n * returns NULL otherwise. * @since 12 * @version 1.0 */ OH_NativeImage* OH_ConsumerSurface_Create(); /** * @brief Set the default usage of the OH_NativeImage.\n * This interface dose not support concurrency.\n * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param usage Indicates the usage of the OH_NativeImage.Refer to the enum OH_NativeBuffer_Usage. * @return {@link NATIVE_ERROR_OK} 0 - Success. * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. * @since 13 * @version 1.0 */ int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage); /** * @brief Set the default size of the OH_NativeImage.\n * This interface dose not support concurrency.\n * * @syscap SystemCapability.Graphic.Graphic2D.NativeImage * @param image Indicates the pointer to a OH_NativeImage instance. * @param width Indicates the width of the OH_NativeImage, and it should be greater than 0. * @param height Indicates the height of the OH_NativeImage, and it should be greater than 0. * @return {@link NATIVE_ERROR_OK} 0 - Success. * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL or width, height less than or equal to 0. * @since 13 * @version 1.0 */ int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height); #ifdef __cplusplus } #endif /** @} */ #endif