VLC  4.0.0-dev
vlc_es_out.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_es_out.h: es_out (demuxer output) descriptor, queries and methods
3  *****************************************************************************
4  * Copyright (C) 1999-2004 VLC authors and VideoLAN
5  *
6  * Authors: Laurent Aimar <fenrir@via.ecp.fr>
7  *
8  * This program is free software; you can redistribute it and/or modify it
9  * under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 2.1 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16  * GNU Lesser General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
21  *****************************************************************************/
22 
23 #ifndef VLC_ES_OUT_H
24 #define VLC_ES_OUT_H 1
25 
26 #include <assert.h>
27 
28 /**
29  * \defgroup es_out ES output
30  * \ingroup input
31  * Elementary streams output
32  * @{
33  * \file
34  * Elementary streams output interface
35  */
36 
37 enum es_out_query_e
38 {
39  /* set or change the selected ES in its category (audio/video/spu) */
40  ES_OUT_SET_ES, /* arg1= es_out_id_t* */
41  ES_OUT_UNSET_ES, /* arg1= es_out_id_t* res=can fail */
42  ES_OUT_RESTART_ES, /* arg1= es_out_id_t* */
43 
44  /* set 'default' tag on ES (copied across from container) */
45  ES_OUT_SET_ES_DEFAULT, /* arg1= es_out_id_t* */
46 
47  /* force (un)selection of the ES (bypass current mode)
48  XXX: this will not change the state of any other ES ! (see SET_ES) */
49  ES_OUT_SET_ES_STATE,/* arg1= es_out_id_t* arg2=bool */
50  ES_OUT_GET_ES_STATE,/* arg1= es_out_id_t* arg2=bool* */
51 
52  /* sets es selection policy when in auto mode */
53  ES_OUT_SET_ES_CAT_POLICY, /* arg1=es_format_category_e arg2=es_out_policy_e */
54 
55  /* */
56  ES_OUT_SET_GROUP, /* arg1= int */
57 
58  /* PCR handling, DTS/PTS will be automatically computed using thoses PCR
59  * XXX: SET_PCR(_GROUP) are in charge of the pace control. They will wait
60  * to slow down the demuxer so that it reads at the right speed.
61  * XXX: if you want PREROLL just call ES_OUT_SET_NEXT_DISPLAY_TIME and send
62  * as you would normally do.
63  */
64  ES_OUT_SET_PCR, /* arg1=vlc_tick_t i_pcr(microsecond!) (using default group 0)*/
65  ES_OUT_SET_GROUP_PCR, /* arg1= int i_group, arg2=vlc_tick_t i_pcr(microsecond!)*/
66  ES_OUT_RESET_PCR, /* no arg */
67 
68  /* This will update the fmt, drain and restart the decoder (if any).
69  * The new fmt must have the same i_cat and i_id. */
70  ES_OUT_SET_ES_FMT, /* arg1= es_out_id_t* arg2=es_format_t* res=can fail */
71 
72  /* Allow preroll of data (data with dts/pts < i_pts for all ES will be decoded but not displayed */
73  ES_OUT_SET_NEXT_DISPLAY_TIME, /* arg1=int64_t i_pts(microsecond) */
74  /* Set meta data for group (dynamic) (The vlc_meta_t is not modified nor released) */
75  ES_OUT_SET_GROUP_META, /* arg1=int i_group arg2=const vlc_meta_t */
76  /* Set epg for group (dynamic) (The vlc_epg_t is not modified nor released) */
77  ES_OUT_SET_GROUP_EPG, /* arg1=int i_group arg2=const vlc_epg_t * */
78  ES_OUT_SET_GROUP_EPG_EVENT, /* arg1=int i_group arg2=const vlc_epg_event_t * */
79  ES_OUT_SET_EPG_TIME, /* arg1=int int64_t */
80 
81  /* */
82  ES_OUT_DEL_GROUP, /* arg1=int i_group */
83 
84  /* Set scrambled state for one es */
85  ES_OUT_SET_ES_SCRAMBLED_STATE, /* arg1=int i_group arg2=es_out_id_t* */
86 
87  /* Stop any buffering being done, and ask if es_out has no more data to
88  * play.
89  * It will not block and so MUST be used carrefully. The only good reason
90  * is for interactive playback (like for DVD menu).
91  * XXX You SHALL call ES_OUT_RESET_PCR before any other es_out_Control/Send calls. */
92  ES_OUT_GET_EMPTY, /* arg1=bool* res=cannot fail */
93 
94  /* Set global meta data (The vlc_meta_t is not modified nor released) */
95  ES_OUT_SET_META, /* arg1=const vlc_meta_t * */
96 
97  /* PCR system clock manipulation for external clock synchronization */
98  ES_OUT_GET_PCR_SYSTEM, /* arg1=vlc_tick_t *, arg2=vlc_tick_t * res=can fail */
99  ES_OUT_MODIFY_PCR_SYSTEM, /* arg1=int is_absolute, arg2=vlc_tick_t, res=can fail */
100 
101  ES_OUT_POST_SUBNODE, /* arg1=input_item_node_t *, res=can fail */
102 
103  ES_OUT_VOUT_SET_MOUSE_EVENT, /* arg1= es_out_id_t* (video es),
104  arg2=vlc_mouse_event, arg3=void *(user_data),
105  res=can fail */
106 
107  ES_OUT_VOUT_ADD_OVERLAY, /* arg1= es_out_id_t* (video es),
108  * arg2= subpicture_t *,
109  * arg3= size_t * (channel id), res= can fail */
110  ES_OUT_VOUT_DEL_OVERLAY, /* arg1= es_out_id_t* (video es),
111  * arg2= size_t (channel id), res= can fail */
112 
113  ES_OUT_SPU_SET_HIGHLIGHT, /* arg1= es_out_id_t* (spu es),
114  arg2= const vlc_spu_highlight_t *, res=can fail */
115 
116  /* First value usable for private control */
117  ES_OUT_PRIVATE_START = 0x10000,
118 };
119 
120 enum es_out_policy_e
121 {
122  ES_OUT_ES_POLICY_EXCLUSIVE = 0,/* Enforces single ES selection only */
123  ES_OUT_ES_POLICY_SIMULTANEOUS, /* Allows multiple ES per cat */
124  /* Exclusive by default, and simultaneous if specifically requested more
125  * than one track at once */
127 };
128 
129 struct es_out_callbacks
130 {
131  es_out_id_t *(*add)(es_out_t *, input_source_t *in, const es_format_t *);
132  int (*send)(es_out_t *, es_out_id_t *, block_t *);
133  void (*del)(es_out_t *, es_out_id_t *);
134  int (*control)(es_out_t *, input_source_t *in, int query, va_list);
135  void (*destroy)(es_out_t *);
136  /**
137  * Private control callback, must be NULL for es_out created from modules.
138  */
139  int (*priv_control)(es_out_t *, int query, va_list);
140 };
141 
142 struct es_out_t
143 {
144  const struct es_out_callbacks *cbs;
145 };
146 
147 VLC_USED
148 static inline es_out_id_t * es_out_Add( es_out_t *out, const es_format_t *fmt )
149 {
150  return out->cbs->add( out, NULL, fmt );
151 }
152 
153 static inline void es_out_Del( es_out_t *out, es_out_id_t *id )
154 {
155  out->cbs->del( out, id );
156 }
157 
158 static inline int es_out_Send( es_out_t *out, es_out_id_t *id,
159  block_t *p_block )
160 {
161  return out->cbs->send( out, id, p_block );
162 }
163 
164 static inline int es_out_vaControl( es_out_t *out, int i_query, va_list args )
165 {
166  return out->cbs->control( out, NULL, i_query, args );
167 }
168 
169 static inline int es_out_Control( es_out_t *out, int i_query, ... )
170 {
171  va_list args;
172  int i_result;
173 
174  va_start( args, i_query );
175  i_result = es_out_vaControl( out, i_query, args );
176  va_end( args );
177  return i_result;
178 }
179 
180 static inline void es_out_Delete( es_out_t *p_out )
181 {
182  p_out->cbs->destroy( p_out );
183 }
184 
185 static inline int es_out_SetPCR( es_out_t *out, vlc_tick_t pcr )
186 {
187  return es_out_Control( out, ES_OUT_SET_PCR, pcr );
188 }
189 
190 static inline int es_out_ControlSetMeta( es_out_t *out, const vlc_meta_t *p_meta )
191 {
192  return es_out_Control( out, ES_OUT_SET_META, p_meta );
193 }
194 
195 static inline int es_out_ControlGetPcrSystem( es_out_t *out, vlc_tick_t *pi_system, vlc_tick_t *pi_delay )
196 {
197  return es_out_Control( out, ES_OUT_GET_PCR_SYSTEM, pi_system, pi_delay );
198 }
199 static inline int es_out_ControlModifyPcrSystem( es_out_t *out, bool b_absolute, vlc_tick_t i_system )
200 {
201  return es_out_Control( out, ES_OUT_MODIFY_PCR_SYSTEM, b_absolute, i_system );
202 }
203 
204 /**
205  * @}
206  */
207 
208 #endif
es_out_callbacks::del
void(* del)(es_out_t *, es_out_id_t *)
Definition: vlc_es_out.h:134
ES_OUT_MODIFY_PCR_SYSTEM
@ ES_OUT_MODIFY_PCR_SYSTEM
Definition: vlc_es_out.h:100
es_out_callbacks::add
es_out_id_t *(* add)(es_out_t *, input_source_t *in, const es_format_t *)
Definition: vlc_es_out.h:132
ES_OUT_PRIVATE_START
@ ES_OUT_PRIVATE_START
Definition: vlc_es_out.h:118
ES_OUT_SET_GROUP_EPG_EVENT
@ ES_OUT_SET_GROUP_EPG_EVENT
Definition: vlc_es_out.h:79
ES_OUT_SET_META
@ ES_OUT_SET_META
Definition: vlc_es_out.h:96
vlc_common.h
ES_OUT_VOUT_SET_MOUSE_EVENT
@ ES_OUT_VOUT_SET_MOUSE_EVENT
Definition: vlc_es_out.h:104
ES_OUT_DEL_GROUP
@ ES_OUT_DEL_GROUP
Definition: vlc_es_out.h:83
ES_OUT_ES_POLICY_EXCLUSIVE
@ ES_OUT_ES_POLICY_EXCLUSIVE
Definition: vlc_es_out.h:123
ES_OUT_SET_NEXT_DISPLAY_TIME
@ ES_OUT_SET_NEXT_DISPLAY_TIME
Definition: vlc_es_out.h:74
ES_OUT_VOUT_DEL_OVERLAY
@ ES_OUT_VOUT_DEL_OVERLAY
Definition: vlc_es_out.h:111
ES_OUT_GET_ES_STATE
@ ES_OUT_GET_ES_STATE
Definition: vlc_es_out.h:51
ES_OUT_ES_POLICY_AUTO
@ ES_OUT_ES_POLICY_AUTO
Definition: vlc_es_out.h:127
ES_OUT_SET_EPG_TIME
@ ES_OUT_SET_EPG_TIME
Definition: vlc_es_out.h:80
ES_OUT_SET_ES_SCRAMBLED_STATE
@ ES_OUT_SET_ES_SCRAMBLED_STATE
Definition: vlc_es_out.h:86
es_out_callbacks::control
int(* control)(es_out_t *, input_source_t *in, int query, va_list)
Definition: vlc_es_out.h:135
ES_OUT_SET_GROUP
@ ES_OUT_SET_GROUP
Definition: vlc_es_out.h:57
es_out_ControlSetMeta
static int es_out_ControlSetMeta(es_out_t *out, const vlc_meta_t *p_meta)
Definition: vlc_es_out.h:191
ES_OUT_GET_PCR_SYSTEM
@ ES_OUT_GET_PCR_SYSTEM
Definition: vlc_es_out.h:99
es_out_ControlGetPcrSystem
static int es_out_ControlGetPcrSystem(es_out_t *out, vlc_tick_t *pi_system, vlc_tick_t *pi_delay)
Definition: vlc_es_out.h:196
ES_OUT_SPU_SET_HIGHLIGHT
@ ES_OUT_SPU_SET_HIGHLIGHT
Definition: vlc_es_out.h:114
es_out_t::cbs
const struct es_out_callbacks * cbs
Definition: vlc_es_out.h:145
vlc_meta_t
Definition: meta.c:39
ES_OUT_SET_ES_DEFAULT
@ ES_OUT_SET_ES_DEFAULT
Definition: vlc_es_out.h:46
es_out_callbacks::priv_control
int(* priv_control)(es_out_t *, int query, va_list)
Private control callback, must be NULL for es_out created from modules.
Definition: vlc_es_out.h:140
es_out_t
Definition: vlc_es_out.h:143
es_out_Add
static es_out_id_t * es_out_Add(es_out_t *out, const es_format_t *fmt)
Definition: vlc_es_out.h:149
es_out_Delete
static void es_out_Delete(es_out_t *p_out)
Definition: vlc_es_out.h:181
es_out_callbacks::send
int(* send)(es_out_t *, es_out_id_t *, block_t *)
Definition: vlc_es_out.h:133
es_out_Control
static int es_out_Control(es_out_t *out, int i_query,...)
Definition: vlc_es_out.h:170
es_out_ControlModifyPcrSystem
static int es_out_ControlModifyPcrSystem(es_out_t *out, bool b_absolute, vlc_tick_t i_system)
Definition: vlc_es_out.h:200
es_format_t
Definition: vlc_es.h:618
vlc_tick_t
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:45
ES_OUT_SET_ES
@ ES_OUT_SET_ES
Definition: vlc_es_out.h:41
es_out_query_e
es_out_query_e
Definition: vlc_es_out.h:38
input_source_t
Definition: input_internal.h:373
ES_OUT_SET_ES_STATE
@ ES_OUT_SET_ES_STATE
Definition: vlc_es_out.h:50
es_out_callbacks
Definition: vlc_es_out.h:130
es_out_id_t
Definition: es_out.c:103
ES_OUT_GET_EMPTY
@ ES_OUT_GET_EMPTY
Definition: vlc_es_out.h:93
es_out_callbacks::destroy
void(* destroy)(es_out_t *)
Definition: vlc_es_out.h:136
ES_OUT_SET_ES_FMT
@ ES_OUT_SET_ES_FMT
Definition: vlc_es_out.h:71
es_out_vaControl
static int es_out_vaControl(es_out_t *out, int i_query, va_list args)
Definition: vlc_es_out.h:165
es_out_Del
static void es_out_Del(es_out_t *out, es_out_id_t *id)
Definition: vlc_es_out.h:154
ES_OUT_RESET_PCR
@ ES_OUT_RESET_PCR
Definition: vlc_es_out.h:67
ES_OUT_SET_PCR
@ ES_OUT_SET_PCR
Definition: vlc_es_out.h:65
VLC_USED
#define VLC_USED
Definition: fourcc_gen.c:32
ES_OUT_ES_POLICY_SIMULTANEOUS
@ ES_OUT_ES_POLICY_SIMULTANEOUS
Definition: vlc_es_out.h:124
ES_OUT_POST_SUBNODE
@ ES_OUT_POST_SUBNODE
Definition: vlc_es_out.h:102
es_out_SetPCR
static int es_out_SetPCR(es_out_t *out, vlc_tick_t pcr)
Definition: vlc_es_out.h:186
ES_OUT_SET_GROUP_META
@ ES_OUT_SET_GROUP_META
Definition: vlc_es_out.h:76
es_out_policy_e
es_out_policy_e
Definition: vlc_es_out.h:121
ES_OUT_SET_GROUP_PCR
@ ES_OUT_SET_GROUP_PCR
Definition: vlc_es_out.h:66
ES_OUT_UNSET_ES
@ ES_OUT_UNSET_ES
Definition: vlc_es_out.h:42
ES_OUT_SET_ES_CAT_POLICY
@ ES_OUT_SET_ES_CAT_POLICY
Definition: vlc_es_out.h:54
ES_OUT_SET_GROUP_EPG
@ ES_OUT_SET_GROUP_EPG
Definition: vlc_es_out.h:78
es_out_Send
static int es_out_Send(es_out_t *out, es_out_id_t *id, block_t *p_block)
Definition: vlc_es_out.h:159
block_t
Definition: vlc_block.h:117
ES_OUT_VOUT_ADD_OVERLAY
@ ES_OUT_VOUT_ADD_OVERLAY
Definition: vlc_es_out.h:108
ES_OUT_RESTART_ES
@ ES_OUT_RESTART_ES
Definition: vlc_es_out.h:43