1 /* 2 * Copyright (C) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup AVImageGenerator 18 * @{ 19 * 20 * @brief Provides APIs for generating an image at the specific time from a video resource. 21 * 22 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 23 * @since 18 24 */ 25 26 /** 27 * @file avimage_generator.h 28 * 29 * @brief Defines the avimage generator APIs. Uses the Native APIs provided by Media AVImageGenerator 30 * to get an image at the specific time from a video resource. 31 * 32 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 33 * @kit MediaKit 34 * @library libavimage_generator.so 35 * @since 18 36 */ 37 38 #ifndef MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVIMAGE_GENERATOR_H 39 #define MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVIMAGE_GENERATOR_H 40 41 #include <stdbool.h> 42 #include <stdint.h> 43 #include <stdio.h> 44 #include "native_averrors.h" 45 #include "avimage_generator_base.h" 46 #include "multimedia/image_framework/image/pixelmap_native.h" 47 48 #ifdef __cplusplus 49 extern "C" { 50 #endif 51 52 /** 53 * @brief Define OH_AVImageGenerator field. 54 * 55 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 56 * @since 18 57 */ 58 typedef struct OH_AVImageGenerator OH_AVImageGenerator; 59 60 /** 61 * @brief Create an image generator. 62 * 63 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 64 * @return Returns a pointer to an OH_AVImageGenerator instance for success, nullptr for failure. 65 * Possible failure causes: HstEngineFactory failed to CreateAVMetadataHelperEngine. 66 * @since 18 67 */ 68 OH_AVImageGenerator* OH_AVImageGenerator_Create(void); 69 70 /** 71 * @brief Sets the media file descriptor source for the image generator. 72 * 73 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 74 * @param generator Pointer to an OH_AVImageGenerator instance. 75 * @param fd Indicates the file descriptor of media source. 76 * @param offset Indicates the offset of media source in file descriptor. 77 * @param size Indicates the size of media source. 78 * @return Function result code. 79 * {@link AV_ERR_OK} if the execution is successful. 80 * {@link AV_ERR_INVALID_VAL} if input generator is nullptr or input param is invalid. 81 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 82 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 83 * @since 18 84 */ 85 OH_AVErrCode OH_AVImageGenerator_SetFDSource(OH_AVImageGenerator* generator, 86 int32_t fd, int64_t offset, int64_t size); 87 88 /** 89 * @brief Fetch an image at the specific time from a video resource. 90 * 91 * This function must be called after {@link SetFDSource}. 92 * 93 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 94 * @param generator Pointer to an OH_AVImageGenerator instance. 95 * @param timeUs The time expected to fetch picture from the video resource. The unit is microsecond(us). 96 * @param options The time options about the relationship between the given timeUs and a key frame, 97 * see {@link OH_AVImageGenerator_QueryOptions}. 98 * @param pixelMap The fetched output image from the video source. For details, see {@link OH_PixelmapNative}. 99 * @return Function result code. 100 * {@link AV_ERR_OK} if the execution is successful. 101 * {@link AV_ERR_INVALID_VAL} if input generator is nullptr or input param is invalid. 102 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 103 * {@link AV_ERR_UNSUPPORTED_FORMAT} if format is unsupported. 104 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 105 * @since 18 106 */ 107 OH_AVErrCode OH_AVImageGenerator_FetchFrameByTime(OH_AVImageGenerator* generator, 108 int64_t timeUs, OH_AVImageGenerator_QueryOptions options, OH_PixelmapNative** pixelMap); 109 110 /** 111 * @brief Release the resource used for AVImageGenerator. 112 * 113 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 114 * @param generator Pointer to an OH_AVImageGenerator instance. 115 * @return Function result code. 116 * {@link AV_ERR_OK} if the execution is successful. 117 * {@link AV_ERR_INVALID_VAL} if input generator is nullptr or input param is invalid. 118 * @since 18 119 */ 120 OH_AVErrCode OH_AVImageGenerator_Release(OH_AVImageGenerator* generator); 121 122 #ifdef __cplusplus 123 } 124 #endif 125 126 #endif // MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVIMAGE_GENERATOR_H 127 /** @} */ 128