1/*****************************************************************************
2 * vlc_picture.h: picture definitions
3 *****************************************************************************
4 * Copyright (C) 1999 - 2009 VLC authors and VideoLAN
5 * $Id: 74f156fbbd6e6a4479754c0e79fbd5374a4a1e2e $
6 *
7 * Authors: Vincent Seguin <seguin@via.ecp.fr>
8 * Samuel Hocevar <sam@via.ecp.fr>
9 * Olivier Aubert <oaubert 47 videolan d07 org>
10 *
11 * This program is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU Lesser General Public License as published by
13 * the Free Software Foundation; either version 2.1 of the License, or
14 * (at your option) any later version.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * along with this program; if not, write to the Free Software Foundation,
23 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24 *****************************************************************************/
25
26#ifndef VLC_PICTURE_H
27#define VLC_PICTURE_H 1
28
29/**
30 * \file
31 * This file defines picture structures and functions in vlc
32 */
33
34#include <vlc_es.h>
35
36/** Description of a planar graphic field */
37typedef struct plane_t
38{
39 uint8_t *p_pixels; /**< Start of the plane's data */
40
41 /* Variables used for fast memcpy operations */
42 int i_lines; /**< Number of lines, including margins */
43 int i_pitch; /**< Number of bytes in a line, including margins */
44
45 /** Size of a macropixel, defaults to 1 */
46 int i_pixel_pitch;
47
48 /* Variables used for pictures with margins */
49 int i_visible_lines; /**< How many visible lines are there ? */
50 int i_visible_pitch; /**< How many visible pixels are there ? */
51
52} plane_t;
53
54/**
55 * Maximum number of plane for a picture
56 */
57#define PICTURE_PLANE_MAX (VOUT_MAX_PLANES)
58
59typedef struct picture_context_t
60{
61 void (*destroy)(struct picture_context_t *);
62 struct picture_context_t *(*copy)(struct picture_context_t *);
63} picture_context_t;
64
65/**
66 * Video picture
67 */
68struct picture_t
69{
70 /**
71 * The properties of the picture
72 */
73 video_frame_format_t format;
74
75 plane_t p[PICTURE_PLANE_MAX]; /**< description of the planes */
76 int i_planes; /**< number of allocated planes */
77
78 /** \name Picture management properties
79 * These properties can be modified using the video output thread API,
80 * but should never be written directly */
81 /**@{*/
82 mtime_t date; /**< display date */
83 bool b_force;
84 /**@}*/
85
86 /** \name Picture dynamic properties
87 * Those properties can be changed by the decoder
88 * @{
89 */
90 bool b_progressive; /**< is it a progressive frame ? */
91 bool b_top_field_first; /**< which field is first */
92 unsigned int i_nb_fields; /**< # of displayed fields */
93 picture_context_t *context; /**< video format-specific data pointer */
94 /**@}*/
95
96 /** Private data - the video output plugin might want to put stuff here to
97 * keep track of the picture */
98 picture_sys_t * p_sys;
99
100 /** Next picture in a FIFO a pictures */
101 struct picture_t *p_next;
102};
103
104/**
105 * This function will create a new picture.
106 * The picture created will implement a default release management compatible
107 * with picture_Hold and picture_Release. This default management will release
108 * p_sys, gc.p_sys fields if non NULL.
109 */
110VLC_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;
111
112/**
113 * This function will create a new picture using the given format.
114 *
115 * When possible, it is preferred to use this function over picture_New
116 * as more information about the format is kept.
117 */
118VLC_API picture_t * picture_NewFromFormat( const video_format_t *p_fmt ) VLC_USED;
119
120/**
121 * Resource for a picture.
122 */
123typedef struct
124{
125 picture_sys_t *p_sys;
126 void (*pf_destroy)(picture_t *);
127
128 /* Plane resources
129 * XXX all fields MUST be set to the right value.
130 */
131 struct
132 {
133 uint8_t *p_pixels; /**< Start of the plane's data */
134 int i_lines; /**< Number of lines, including margins */
135 int i_pitch; /**< Number of bytes in a line, including margins */
136 } p[PICTURE_PLANE_MAX];
137
138} picture_resource_t;
139
140/**
141 * This function will create a new picture using the provided resource.
142 *
143 * If the resource is NULL then a plain picture_NewFromFormat is returned.
144 */
145VLC_API picture_t * picture_NewFromResource( const video_format_t *, const picture_resource_t * ) VLC_USED;
146
147/**
148 * This function will increase the picture reference count.
149 * It will not have any effect on picture obtained from vout
150 *
151 * It returns the given picture for convenience.
152 */
153VLC_API picture_t *picture_Hold( picture_t *p_picture );
154
155/**
156 * This function will release a picture.
157 * It will not have any effect on picture obtained from vout
158 */
159VLC_API void picture_Release( picture_t *p_picture );
160
161/**
162 * This function will copy all picture dynamic properties.
163 */
164VLC_API void picture_CopyProperties( picture_t *p_dst, const picture_t *p_src );
165
166/**
167 * This function will reset a picture information (properties and quantizers).
168 * It is sometimes useful for reusing pictures (like from a pool).
169 */
170VLC_API void picture_Reset( picture_t * );
171
172/**
173 * This function will copy the picture pixels.
174 * You can safely copy between pictures that do not have the same size,
175 * only the compatible(smaller) part will be copied.
176 */
177VLC_API void picture_CopyPixels( picture_t *p_dst, const picture_t *p_src );
178VLC_API void plane_CopyPixels( plane_t *p_dst, const plane_t *p_src );
179
180/**
181 * This function will copy both picture dynamic properties and pixels.
182 * You have to notice that sometime a simple picture_Hold may do what
183 * you want without the copy overhead.
184 * Provided for convenience.
185 *
186 * \param p_dst pointer to the destination picture.
187 * \param p_src pointer to the source picture.
188 */
189VLC_API void picture_Copy( picture_t *p_dst, const picture_t *p_src );
190
191/**
192 * Perform a shallow picture copy
193 *
194 * This function makes a shallow copy of an existing picture. The same planes
195 * and resources will be used, and the cloned picture reference count will be
196 * incremented.
197 *
198 * \return A clone picture on success, NULL on error.
199 */
200VLC_API picture_t *picture_Clone(picture_t *pic);
201
202/**
203 * This function will export a picture to an encoded bitstream.
204 *
205 * pp_image will contain the encoded bitstream in psz_format format.
206 *
207 * p_fmt can be NULL otherwise it will be set with the format used for the
208 * picture before encoding.
209 *
210 * i_override_width/height allow to override the width and/or the height of the
211 * picture to be encoded:
212 * - if strictly lower than 0, the original dimension will be used.
213 * - if equal to 0, it will be deduced from the other dimension which must be
214 * different to 0.
215 * - if strictly higher than 0, it will override the dimension.
216 * If at most one of them is > 0 then the picture aspect ratio will be kept.
217 */
218VLC_API int picture_Export( vlc_object_t *p_obj, block_t **pp_image, video_format_t *p_fmt, picture_t *p_picture, vlc_fourcc_t i_format, int i_override_width, int i_override_height );
219
220/**
221 * This function will setup all fields of a picture_t without allocating any
222 * memory.
223 * XXX The memory must already be initialized.
224 * It does not need to be released.
225 *
226 * It will return VLC_EGENERIC if the core does not understand the requested
227 * format.
228 *
229 * It can be useful to get the properties of planes.
230 */
231VLC_API int picture_Setup( picture_t *, const video_format_t * );
232
233
234/*****************************************************************************
235 * Shortcuts to access image components
236 *****************************************************************************/
237
238/* Plane indices */
239enum
240{
241 Y_PLANE = 0,
242 U_PLANE = 1,
243 V_PLANE = 2,
244 A_PLANE = 3,
245};
246
247/* Shortcuts */
248#define Y_PIXELS p[Y_PLANE].p_pixels
249#define Y_PITCH p[Y_PLANE].i_pitch
250#define U_PIXELS p[U_PLANE].p_pixels
251#define U_PITCH p[U_PLANE].i_pitch
252#define V_PIXELS p[V_PLANE].p_pixels
253#define V_PITCH p[V_PLANE].i_pitch
254#define A_PIXELS p[A_PLANE].p_pixels
255#define A_PITCH p[A_PLANE].i_pitch
256
257/**@}*/
258
259#endif /* VLC_PICTURE_H */
260

source code of include/vlc/plugins/vlc_picture.h