1 /*
2  * Copyright (C) 2021 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 #ifndef IAVMETADATAHELPER_SERVICE_H
17 #define IAVMETADATAHELPER_SERVICE_H
18 
19 #include "avmetadatahelper.h"
20 #include "buffer/avsharedmemory.h"
21 #include "meta/meta.h"
22 
23 namespace OHOS {
24 namespace Media {
25 struct OutputFrame {
26 public:
OutputFrameOutputFrame27     OutputFrame(int32_t width, int32_t height, int32_t stride, int32_t bytesPerPixel)
28         : width_(width),
29           height_(height),
30           stride_(stride),
31           bytesPerPixel_(bytesPerPixel),
32           size_(stride_ * height),  // interleaved layout
33           rotation_(0)
34     {
35     }
36 
GetFlattenedSizeOutputFrame37     int32_t GetFlattenedSize() const
38     {
39         return sizeof(OutputFrame) + size_;
40     }
41 
GetFlattenedDataOutputFrame42     uint8_t *GetFlattenedData() const
43     {
44         return const_cast<uint8_t *>(reinterpret_cast<const uint8_t *>(this)) + sizeof(OutputFrame);
45     }
46 
47     int32_t width_;
48     int32_t height_;
49     int32_t stride_;  // interleaved layout
50     int32_t bytesPerPixel_;
51     int32_t size_;
52     int32_t rotation_;
53 };
54 
55 struct OutputConfiguration {
56     int32_t dstWidth = -1;
57     int32_t dstHeight = -1;
58     PixelFormat colorFormat = PixelFormat::RGB_565;
59 
60     bool operator==(const OutputConfiguration &other) const
61     {
62         return dstWidth == other.dstWidth && dstHeight == other.dstHeight && colorFormat == other.colorFormat;
63     }
64 };
65 
66 class IAVMetadataHelperService {
67 public:
68     virtual ~IAVMetadataHelperService() = default;
69 
70     /**
71      * @brief Method to set helper callback.
72      *
73      * @param callback object pointer.
74      * @return Returns {@link MSERR_OK} if the helpercallback is set; returns an error code defined
75      * in {@link media_errors.h} otherwise.
76      */
77     virtual int32_t SetHelperCallback(const std::shared_ptr<HelperCallback> &callback) = 0;
78 
79     /**
80      * Set the media source uri to use. Calling this method before the reset
81      * of the methods in this class. This method maybe time consuming.
82      * @param uri the URI of input media source.
83      * @param usage indicates which scene the avmedatahelper's instance will
84      * be used to, see {@link AVMetadataUsage}. If the usage need to be changed,
85      * this method must be called again.
86      * @return Returns {@link MSERR_OK} if the setting is successful; returns
87      * an error code otherwise.
88      */
89     virtual int32_t SetSource(const std::string &uri, int32_t usage) = 0;
90 
91     /**
92      * @brief Sets the media file descriptor source to resolve. Calling this method
93      * before the reset of the methods in this class. This method maybe time consuming.
94      * @param fd Indicates the file descriptor of media source.
95      * @param offset Indicates the offset of media source in file descriptor.
96      * @param size Indicates the size of media source.
97      * @param usage Indicates which scene the avmedatahelper's instance will
98      * be used to, see {@link AVMetadataUsage}. If the usage need to be changed,
99      * this method must be called again.
100      * @return Returns {@link MSERR_OK} if the setting is successful; returns
101      * an error code otherwise.
102      */
103     virtual int32_t SetSource(int32_t fd, int64_t offset, int64_t size, int32_t usage) = 0;
104 
105     /**
106      * Sets the media data source to resolve.
107      * @param dataSrc A data source instance with the fileSize and a callback {@link IMediaDataSource}.
108      * @return Returns the status code.
109      */
110     virtual int32_t SetSource(const std::shared_ptr<IMediaDataSource> &dataSrc) = 0;
111 
112     /**
113      * Retrieve the meta data associated with the specified key. This method can be
114      * called after the SetSource.
115      * @param key One of the constants listed above at the definition of {@link AVMetadataCode}.
116      * @return Returns the meta data value associate with the given key code on
117      * success; empty string on failure.
118      */
119     virtual std::string ResolveMetadata(int32_t key) = 0;
120 
121     /**
122      * Fetch the album art picture associated with the data source. If there are
123      * more than one pictures, the cover image will be returned preferably.
124      * @return Returns the a chunk of shared memory containing a picture, which can be
125      * null, if such a picture can not be fetched.
126      */
127     virtual std::shared_ptr<AVSharedMemory> FetchArtPicture() = 0;
128 
129     /**
130      * Retrieve all meta data within the listed above at the definition of {@link AVMetadataCode}.
131      * This method must be called after the SetSource.
132      * @return Returns the meta data values on success; empty hash map on failure.
133      */
134     virtual std::unordered_map<int32_t, std::string> ResolveMetadata() = 0;
135 
136     /**
137      * get all avmetadata.
138      * This method must be called after the SetSource.
139      * @return Returns the meta data values on success; nullptr on failure.
140      */
141     virtual std::shared_ptr<Meta> GetAVMetadata() = 0;
142 
143     /**
144      * Fetch a representative video frame near a given timestamp by considering the given
145      * option if possible, and return a video frame with given parameters. This method must be
146      * called after the SetSource.
147      * @param timeMs The time position in microseconds where the frame will be fetched.
148      * When fetching the frame at the given time position, there is no guarantee that
149      * the video source has a frame located at the position. When this happens, a frame
150      * nearby will be returned. If timeUs is negative, time position and option will ignored,
151      * and any frame that the implementation considers as representative may be returned.
152      * @param option the hint about how to fetch a frame, see {@link AVMetadataQueryOption}
153      * @param param the desired configuration of returned video frame, see {@link OutputConfiguration}.
154      * @return Returns a chunk of shared memory containing a scaled video frame, which
155      * can be null, if such a frame cannot be fetched.
156      */
157     virtual std::shared_ptr<AVSharedMemory> FetchFrameAtTime(
158         int64_t timeUs, int32_t option, const OutputConfiguration &param) = 0;
159 
160     /**
161      * Fetch a representative video frame near a given timestamp by considering the given
162      * option if possible, and return a video frame with given parameters. This method must be
163      * called after the SetSource.
164      * @param timeMs The time position in microseconds where the frame will be fetched.
165      * When fetching the frame at the given time position, there is no guarantee that
166      * the video source has a frame located at the position. When this happens, a frame
167      * nearby will be returned. If timeUs is negative, time position and option will ignored,
168      * and any frame that the implementation considers as representative may be returned.
169      * @param option the hint about how to fetch a frame, see {@link AVMetadataQueryOption}
170      * @param param the desired configuration of returned video frame, see {@link OutputConfiguration}.
171      * @return Returns a chunk of shared memory containing a scaled video frame, which
172      * can be null, if such a frame cannot be fetched.
173      */
174     virtual std::shared_ptr<AVBuffer> FetchFrameYuv(
175         int64_t timeUs, int32_t option, const OutputConfiguration &param) = 0;
176 
177     /**
178      * Release the internel resource. After this method called, the service instance
179      * can not be used again.
180      */
181     virtual void Release() = 0;
182 
183     /**
184      * Get timestamp according to frame index.
185      * @param timeUs : Index of the frame.
186      * @returns returns time
187      */
188     virtual int32_t GetTimeByFrameIndex(uint32_t index, uint64_t &time) = 0;
189 
190     /**
191      * Get frame index according to the given timestamp.
192      * @param timeUs : Timestamp of the frame, in microseconds.
193      * @returns Returns frame
194      */
195     virtual int32_t GetFrameIndexByTime(uint64_t time, uint32_t &index) = 0;
196 };
197 }  // namespace Media
198 }  // namespace OHOS
199 
200 #endif