1 /*****************************************************************************
2 * vlc_picture.h: picture definitions
3 *****************************************************************************
4 * Copyright (C) 1999 - 2009 VLC authors and VideoLAN
6 * Authors: Vincent Seguin <seguin@via.ecp.fr>
7 * Samuel Hocevar <sam@via.ecp.fr>
8 * Olivier Aubert <oaubert 47 videolan d07 org>
10 * This program is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU Lesser General Public License as published by
12 * the Free Software Foundation; either version 2.1 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public License
21 * along with this program; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23 *****************************************************************************/
26 #define VLC_PICTURE_H 1
30 #include <stdatomic.h>
33 using std::atomic_uintptr_t
;
34 using std::memory_order_relaxed
;
35 using std::memory_order_release
;
40 * This file defines picture structures and functions in vlc
45 /** Description of a planar graphic field */
46 typedef struct plane_t
48 uint8_t *p_pixels
; /**< Start of the plane's data */
50 /* Variables used for fast memcpy operations */
51 int i_lines
; /**< Number of lines, including margins */
52 int i_pitch
; /**< Number of bytes in a line, including margins */
54 /** Size of a macropixel, defaults to 1 */
57 /* Variables used for pictures with margins */
58 int i_visible_lines
; /**< How many visible lines are there? */
59 int i_visible_pitch
; /**< How many visible pixels are there? */
64 * Maximum number of plane for a picture
66 #define PICTURE_PLANE_MAX (VOUT_MAX_PLANES)
68 typedef struct picture_context_t
70 void (*destroy
)(struct picture_context_t
*);
71 struct picture_context_t
*(*copy
)(struct picture_context_t
*);
72 struct vlc_video_context
*vctx
;
75 typedef struct picture_buffer_t
83 typedef struct vlc_decoder_device vlc_decoder_device
;
84 typedef struct vlc_video_context vlc_video_context
;
86 struct vlc_video_context_operations
88 void (*destroy
)(void *priv
);
91 /** Decoder device type */
92 enum vlc_video_context_type
94 VLC_VIDEO_CONTEXT_NONE
,
95 VLC_VIDEO_CONTEXT_VAAPI
,
96 VLC_VIDEO_CONTEXT_VDPAU
,
97 VLC_VIDEO_CONTEXT_DXVA2
, /**< private: d3d9_video_context_t* */
98 VLC_VIDEO_CONTEXT_D3D11VA
, /**< private: d3d11_video_context_t* */
99 VLC_VIDEO_CONTEXT_AWINDOW
, /**< private: android_video_context_t* */
100 VLC_VIDEO_CONTEXT_NVDEC
,
101 VLC_VIDEO_CONTEXT_CVPX
,
102 VLC_VIDEO_CONTEXT_MMAL
,
105 VLC_API vlc_video_context
* vlc_video_context_Create(vlc_decoder_device
*,
106 enum vlc_video_context_type private_type
,
108 const struct vlc_video_context_operations
*);
109 VLC_API
void vlc_video_context_Release(vlc_video_context
*);
111 VLC_API
enum vlc_video_context_type
vlc_video_context_GetType(const vlc_video_context
*);
112 VLC_API
void *vlc_video_context_GetPrivate(vlc_video_context
*, enum vlc_video_context_type
);
113 VLC_API vlc_video_context
*vlc_video_context_Hold(vlc_video_context
*);
116 * Get the decoder device used by the device context.
118 * This will increment the refcount of the decoder device.
120 VLC_API vlc_decoder_device
*vlc_video_context_HoldDevice(vlc_video_context
*);
129 * The properties of the picture
131 video_frame_format_t format
;
133 plane_t p
[PICTURE_PLANE_MAX
]; /**< description of the planes */
134 int i_planes
; /**< number of allocated planes */
136 /** \name Picture management properties
137 * These properties can be modified using the video output thread API,
138 * but should never be written directly */
140 vlc_tick_t date
; /**< display date */
145 /** \name Picture dynamic properties
146 * Those properties can be changed by the decoder
149 bool b_progressive
; /**< is it a progressive frame? */
150 bool b_top_field_first
; /**< which field is first */
151 unsigned int i_nb_fields
; /**< number of displayed fields */
152 picture_context_t
*context
; /**< video format-specific data pointer */
155 /** Private data - the video output plugin might want to put stuff here to
156 * keep track of the picture */
159 /** Next picture in a FIFO a pictures */
160 struct picture_t
*p_next
;
162 atomic_uintptr_t refs
;
165 static inline vlc_video_context
* picture_GetVideoContext(picture_t
*pic
)
167 return pic
->context
? pic
->context
->vctx
: NULL
;
171 * This function will create a new picture.
172 * The picture created will implement a default release management compatible
173 * with picture_Hold and picture_Release. This default management will release
174 * p_sys, gc.p_sys fields if non NULL.
176 VLC_API picture_t
* picture_New( vlc_fourcc_t i_chroma
, int i_width
, int i_height
, int i_sar_num
, int i_sar_den
) VLC_USED
;
179 * This function will create a new picture using the given format.
181 * When possible, it is preferred to use this function over picture_New
182 * as more information about the format is kept.
184 VLC_API picture_t
* picture_NewFromFormat( const video_format_t
*p_fmt
) VLC_USED
;
187 * Resource for a picture.
192 void (*pf_destroy
)(picture_t
*);
195 * XXX all fields MUST be set to the right value.
199 uint8_t *p_pixels
; /**< Start of the plane's data */
200 int i_lines
; /**< Number of lines, including margins */
201 int i_pitch
; /**< Number of bytes in a line, including margins */
202 } p
[PICTURE_PLANE_MAX
];
204 } picture_resource_t
;
207 * This function will create a new picture using the provided resource.
209 * If the resource is NULL then a plain picture_NewFromFormat is returned.
211 VLC_API picture_t
* picture_NewFromResource( const video_format_t
*, const picture_resource_t
* ) VLC_USED
;
214 * Destroys a picture without references.
216 * This function destroys a picture with zero references left.
217 * Never call this function directly. Use picture_Release() instead.
219 VLC_API
void picture_Destroy(picture_t
*picture
);
222 * Increments the picture reference count.
226 static inline picture_t
*picture_Hold(picture_t
*picture
)
228 atomic_fetch_add_explicit(&picture
->refs
, (uintptr_t)1,
229 memory_order_relaxed
);
234 * Decrements the picture reference count.
236 * If the reference count reaches zero, the picture is destroyed. If it was
237 * allocated from a pool, the underlying picture buffer will be returned to the
238 * pool. Otherwise, the picture buffer will be freed.
240 static inline void picture_Release(picture_t
*picture
)
242 uintptr_t refs
= atomic_fetch_sub_explicit(&picture
->refs
, (uintptr_t)1,
243 memory_order_release
);
244 vlc_assert(refs
> 0);
246 picture_Destroy(picture
);
250 * This function will copy all picture dynamic properties.
252 VLC_API
void picture_CopyProperties( picture_t
*p_dst
, const picture_t
*p_src
);
255 * This function will reset a picture information (properties and quantizers).
256 * It is sometimes useful for reusing pictures (like from a pool).
258 VLC_API
void picture_Reset( picture_t
* );
261 * This function will copy the picture pixels.
262 * You can safely copy between pictures that do not have the same size,
263 * only the compatible(smaller) part will be copied.
265 VLC_API
void picture_CopyPixels( picture_t
*p_dst
, const picture_t
*p_src
);
266 VLC_API
void plane_CopyPixels( plane_t
*p_dst
, const plane_t
*p_src
);
269 * This function will copy both picture dynamic properties and pixels.
270 * You have to notice that sometime a simple picture_Hold may do what
271 * you want without the copy overhead.
272 * Provided for convenience.
274 * \param p_dst pointer to the destination picture.
275 * \param p_src pointer to the source picture.
277 VLC_API
void picture_Copy( picture_t
*p_dst
, const picture_t
*p_src
);
280 * Perform a shallow picture copy
282 * This function makes a shallow copy of an existing picture. The same planes
283 * and resources will be used, and the cloned picture reference count will be
286 * \return A clone picture on success, NULL on error.
288 VLC_API picture_t
*picture_Clone(picture_t
*pic
);
291 * This function will export a picture to an encoded bitstream.
293 * pp_image will contain the encoded bitstream in psz_format format.
295 * p_fmt can be NULL otherwise it will be set with the format used for the
296 * picture before encoding.
298 * i_override_width/height allow to override the width and/or the height of the
299 * picture to be encoded:
300 * - if strictly lower than 0, the original dimension will be used.
301 * - if equal to 0, it will be deduced from the other dimension which must be
303 * - if strictly higher than 0, it will either override the dimension if b_crop
304 * is false, or crop the picture to the provided size if b_crop is true.
305 * If at most one of them is > 0 then the picture aspect ratio will be kept.
307 VLC_API
int picture_Export( vlc_object_t
*p_obj
, block_t
**pp_image
, video_format_t
*p_fmt
,
308 picture_t
*p_picture
, vlc_fourcc_t i_format
, int i_override_width
,
309 int i_override_height
, bool b_crop
);
312 * This function will setup all fields of a picture_t without allocating any
314 * XXX The memory must already be initialized.
315 * It does not need to be released.
317 * It will return VLC_EGENERIC if the core does not understand the requested
320 * It can be useful to get the properties of planes.
322 VLC_API
int picture_Setup( picture_t
*, const video_format_t
* );
325 /*****************************************************************************
326 * Shortcuts to access image components
327 *****************************************************************************/
339 #define Y_PIXELS p[Y_PLANE].p_pixels
340 #define Y_PITCH p[Y_PLANE].i_pitch
341 #define U_PIXELS p[U_PLANE].p_pixels
342 #define U_PITCH p[U_PLANE].i_pitch
343 #define V_PIXELS p[V_PLANE].p_pixels
344 #define V_PITCH p[V_PLANE].i_pitch
345 #define A_PIXELS p[A_PLANE].p_pixels
346 #define A_PITCH p[A_PLANE].i_pitch
349 * Swap UV planes of a Tri Planars picture.
351 * It just swap the planes information without doing any copy.
353 static inline void picture_SwapUV(picture_t
*picture
)
355 vlc_assert(picture
->i_planes
== 3);
357 plane_t tmp_plane
= picture
->p
[U_PLANE
];
358 picture
->p
[U_PLANE
] = picture
->p
[V_PLANE
];
359 picture
->p
[V_PLANE
] = tmp_plane
;
364 #endif /* VLC_PICTURE_H */