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 16 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 * @kit MediaKit 33 * @library libavimage_generator.so 34 * @since 16 35 */ 36 37 #ifndef MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVIMAGE_GENERATOR_H 38 #define MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVIMAGE_GENERATOR_H 39 40 #include <stdbool.h> 41 #include <stdint.h> 42 #include <stdio.h> 43 #include "native_averrors.h" 44 #include "avimage_generator_base.h" 45 #include "pixelmap_native.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Define OH_AVImageGenerator field. 53 * 54 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 55 * @since 16 56 */ 57 typedef struct OH_AVImageGenerator OH_AVImageGenerator; 58 59 /** 60 * @brief Create an image generator. 61 * 62 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 63 * @return Returns a pointer to an OH_AVImageGenerator instance for success, nullptr for failure. 64 * Possible failure causes: HstEngineFactory failed to CreateAVMetadataHelperEngine. 65 * @since 16 66 */ 67 OH_AVImageGenerator* OH_AVImageGenerator_Create(void); 68 69 /** 70 * @brief Sets the media file descriptor source for the image generator. 71 * 72 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 73 * @param generator Pointer to an OH_AVImageGenerator instance. 74 * @param fd Indicates the file descriptor of media source. 75 * @param offset Indicates the offset of media source in file descriptor. 76 * @param size Indicates the size of media source. 77 * @return Function result code. 78 * {@link AV_ERR_OK} if the execution is successful. 79 * {@link AV_ERR_INVALID_VAL} if input generator is nullptr or input param is invalid. 80 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 81 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 82 * @since 16 83 */ 84 OH_AVErrCode OH_AVImageGenerator_SetFDSource(OH_AVImageGenerator* generator, 85 int32_t fd, int64_t offset, int64_t size); 86 87 /** 88 * @brief Fetch an image at the specific time from a video resource. 89 * 90 * This function must be called after {@link SetFDSource}. 91 * 92 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 93 * @param generator Pointer to an OH_AVImageGenerator instance. 94 * @param timeUs The time expected to fetch picture from the video resource. The unit is microsecond(us). 95 * @param options The time options about the relationship between the given timeUs and a key frame, 96 * see {@link OH_AVImageGenerator_QueryOptions}. 97 * @param pixelMap The fetched output image from the video source. For details, see {@link OH_PixelmapNative}. 98 * @return Function result code. 99 * {@link AV_ERR_OK} if the execution is successful. 100 * {@link AV_ERR_INVALID_VAL} if input generator is nullptr or input param is invalid. 101 * {@link AV_ERR_OPERATE_NOT_PERMIT} if operation not allowed. 102 * {@link AV_ERR_UNSUPPORTED_FORMAT} if format is unsupported. 103 * {@link AV_ERR_NO_MEMORY} if internal memory allocation failed. 104 * @since 16 105 */ 106 OH_AVErrCode OH_AVImageGenerator_FetchFrameByTime(OH_AVImageGenerator* generator, 107 int64_t timeUs, OH_AVImageGenerator_QueryOptions options, OH_PixelmapNative** pixelMap); 108 109 /** 110 * @brief Release the resource used for AVImageGenerator. 111 * 112 * @syscap SystemCapability.Multimedia.Media.AVImageGenerator 113 * @param extractor Pointer to an OH_AVImageGenerator instance. 114 * @return Function result code. 115 * {@link AV_ERR_OK} if the execution is successful. 116 * {@link AV_ERR_INVALID_VAL} if input generator is nullptr or input param is invalid. 117 * @since 16 118 */ 119 OH_AVErrCode OH_AVImageGenerator_Release(OH_AVImageGenerator* generator); 120 121 #ifdef __cplusplus 122 } 123 #endif 124 125 #endif // MULTIMEDIA_PLAYER_FRAMEWORK_NATIVE_AVIMAGE_GENERATOR_H