1/* GStreamer Navigation
2 * Copyright (C) 2003 Ronald Bultje <rbultje@ronald.bitfreak.net>
3 * Copyright (C) 2003 David A. Schleef <ds@schleef.org>
4 *
5 * navigation.h: navigation interface design
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Library General Public
9 * License as published by the Free Software Foundation; either
10 * version 2 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Library General Public License for more details.
16 *
17 * You should have received a copy of the GNU Library General Public
18 * License along with this library; if not, write to the
19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23#ifndef __GST_NAVIGATION_H__
24#define __GST_NAVIGATION_H__
25
26#include <gst/gst.h>
27#include <gst/video/video-prelude.h>
28
29G_BEGIN_DECLS
30
31#define GST_TYPE_NAVIGATION \
32 (gst_navigation_get_type ())
33#define GST_NAVIGATION(obj) \
34 (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_NAVIGATION, GstNavigation))
35#define GST_IS_NAVIGATION(obj) \
36 (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_NAVIGATION))
37#define GST_NAVIGATION_GET_INTERFACE(obj) \
38 (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GST_TYPE_NAVIGATION, GstNavigationInterface))
39
40typedef struct _GstNavigation GstNavigation;
41typedef struct _GstNavigationInterface GstNavigationInterface;
42
43/**
44 * GstNavigationInterface:
45 * @iface: the parent interface
46 * @send_event: sending a navigation event
47 *
48 * Navigation interface.
49 */
50struct _GstNavigationInterface {
51 GTypeInterface iface;
52
53 /* virtual functions */
54 void (*send_event) (GstNavigation *navigation, GstStructure *structure);
55};
56
57GST_VIDEO_API
58GType gst_navigation_get_type (void);
59
60/* Navigation commands */
61
62/**
63 * GstNavigationCommand:
64 * @GST_NAVIGATION_COMMAND_INVALID: An invalid command entry
65 * @GST_NAVIGATION_COMMAND_MENU1: Execute navigation menu command 1. For DVD,
66 * this enters the DVD root menu, or exits back to the title from the menu.
67 * @GST_NAVIGATION_COMMAND_MENU2: Execute navigation menu command 2. For DVD,
68 * this jumps to the DVD title menu.
69 * @GST_NAVIGATION_COMMAND_MENU3: Execute navigation menu command 3. For DVD,
70 * this jumps into the DVD root menu.
71 * @GST_NAVIGATION_COMMAND_MENU4: Execute navigation menu command 4. For DVD,
72 * this jumps to the Subpicture menu.
73 * @GST_NAVIGATION_COMMAND_MENU5: Execute navigation menu command 5. For DVD,
74 * the jumps to the audio menu.
75 * @GST_NAVIGATION_COMMAND_MENU6: Execute navigation menu command 6. For DVD,
76 * this jumps to the angles menu.
77 * @GST_NAVIGATION_COMMAND_MENU7: Execute navigation menu command 7. For DVD,
78 * this jumps to the chapter menu.
79 * @GST_NAVIGATION_COMMAND_LEFT: Select the next button to the left in a menu,
80 * if such a button exists.
81 * @GST_NAVIGATION_COMMAND_RIGHT: Select the next button to the right in a menu,
82 * if such a button exists.
83 * @GST_NAVIGATION_COMMAND_UP: Select the button above the current one in a
84 * menu, if such a button exists.
85 * @GST_NAVIGATION_COMMAND_DOWN: Select the button below the current one in a
86 * menu, if such a button exists.
87 * @GST_NAVIGATION_COMMAND_ACTIVATE: Activate (click) the currently selected
88 * button in a menu, if such a button exists.
89 * @GST_NAVIGATION_COMMAND_PREV_ANGLE: Switch to the previous angle in a
90 * multiangle feature.
91 * @GST_NAVIGATION_COMMAND_NEXT_ANGLE: Switch to the next angle in a multiangle
92 * feature.
93 *
94 * A set of commands that may be issued to an element providing the
95 * #GstNavigation interface. The available commands can be queried via
96 * the gst_navigation_query_new_commands() query.
97 *
98 * For convenience in handling DVD navigation, the MENU commands are aliased as:
99 * GST_NAVIGATION_COMMAND_DVD_MENU = @GST_NAVIGATION_COMMAND_MENU1
100 * GST_NAVIGATION_COMMAND_DVD_TITLE_MENU = @GST_NAVIGATION_COMMAND_MENU2
101 * GST_NAVIGATION_COMMAND_DVD_ROOT_MENU = @GST_NAVIGATION_COMMAND_MENU3
102 * GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU = @GST_NAVIGATION_COMMAND_MENU4
103 * GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU = @GST_NAVIGATION_COMMAND_MENU5
104 * GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU = @GST_NAVIGATION_COMMAND_MENU6
105 * GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU = @GST_NAVIGATION_COMMAND_MENU7
106 */
107typedef enum {
108 GST_NAVIGATION_COMMAND_INVALID = 0,
109
110 GST_NAVIGATION_COMMAND_MENU1 = 1,
111 GST_NAVIGATION_COMMAND_MENU2 = 2,
112 GST_NAVIGATION_COMMAND_MENU3 = 3,
113 GST_NAVIGATION_COMMAND_MENU4 = 4,
114 GST_NAVIGATION_COMMAND_MENU5 = 5,
115 GST_NAVIGATION_COMMAND_MENU6 = 6,
116 GST_NAVIGATION_COMMAND_MENU7 = 7,
117
118 GST_NAVIGATION_COMMAND_LEFT = 20,
119 GST_NAVIGATION_COMMAND_RIGHT = 21,
120 GST_NAVIGATION_COMMAND_UP = 22,
121 GST_NAVIGATION_COMMAND_DOWN = 23,
122 GST_NAVIGATION_COMMAND_ACTIVATE = 24,
123
124 GST_NAVIGATION_COMMAND_PREV_ANGLE = 30,
125 GST_NAVIGATION_COMMAND_NEXT_ANGLE = 31
126} GstNavigationCommand;
127
128/* Some aliases for the menu command types */
129#define GST_NAVIGATION_COMMAND_DVD_MENU GST_NAVIGATION_COMMAND_MENU1
130#define GST_NAVIGATION_COMMAND_DVD_TITLE_MENU GST_NAVIGATION_COMMAND_MENU2
131#define GST_NAVIGATION_COMMAND_DVD_ROOT_MENU GST_NAVIGATION_COMMAND_MENU3
132#define GST_NAVIGATION_COMMAND_DVD_SUBPICTURE_MENU GST_NAVIGATION_COMMAND_MENU4
133#define GST_NAVIGATION_COMMAND_DVD_AUDIO_MENU GST_NAVIGATION_COMMAND_MENU5
134#define GST_NAVIGATION_COMMAND_DVD_ANGLE_MENU GST_NAVIGATION_COMMAND_MENU6
135#define GST_NAVIGATION_COMMAND_DVD_CHAPTER_MENU GST_NAVIGATION_COMMAND_MENU7
136
137/* Queries */
138/**
139 * GstNavigationQueryType:
140 * @GST_NAVIGATION_QUERY_INVALID: invalid query
141 * @GST_NAVIGATION_QUERY_COMMANDS: command query
142 * @GST_NAVIGATION_QUERY_ANGLES: viewing angle query
143 *
144 * Tyoes of navigation interface queries.
145 */
146typedef enum
147{
148 GST_NAVIGATION_QUERY_INVALID = 0,
149 GST_NAVIGATION_QUERY_COMMANDS = 1,
150 GST_NAVIGATION_QUERY_ANGLES = 2
151} GstNavigationQueryType;
152
153GST_VIDEO_API
154GstNavigationQueryType gst_navigation_query_get_type (GstQuery *query);
155
156GST_VIDEO_API
157GstQuery * gst_navigation_query_new_commands (void);
158
159GST_VIDEO_API
160void gst_navigation_query_set_commands (GstQuery *query, gint n_cmds, ...);
161
162GST_VIDEO_API
163void gst_navigation_query_set_commandsv (GstQuery *query, gint n_cmds,
164 GstNavigationCommand *cmds);
165
166GST_VIDEO_API
167gboolean gst_navigation_query_parse_commands_length (GstQuery *query,
168 guint *n_cmds);
169
170GST_VIDEO_API
171gboolean gst_navigation_query_parse_commands_nth (GstQuery *query, guint nth,
172 GstNavigationCommand *cmd);
173
174GST_VIDEO_API
175GstQuery * gst_navigation_query_new_angles (void);
176
177GST_VIDEO_API
178void gst_navigation_query_set_angles (GstQuery *query, guint cur_angle,
179 guint n_angles);
180
181GST_VIDEO_API
182gboolean gst_navigation_query_parse_angles (GstQuery *query, guint *cur_angle,
183 guint *n_angles);
184
185/* Element messages */
186/**
187 * GstNavigationMessageType:
188 * @GST_NAVIGATION_MESSAGE_INVALID: Returned from
189 * gst_navigation_message_get_type() when the passed message is not a
190 * navigation message.
191 * @GST_NAVIGATION_MESSAGE_MOUSE_OVER: Sent when the mouse moves over or leaves a
192 * clickable region of the output, such as a DVD menu button.
193 * @GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED: Sent when the set of available commands
194 * changes and should re-queried by interested applications.
195 * @GST_NAVIGATION_MESSAGE_ANGLES_CHANGED: Sent when display angles in a multi-angle
196 * feature (such as a multiangle DVD) change - either angles have appeared or
197 * disappeared.
198 * @GST_NAVIGATION_MESSAGE_EVENT: Sent when a navigation event was not handled
199 * by any element in the pipeline (Since 1.6)
200 *
201 * A set of notifications that may be received on the bus when navigation
202 * related status changes.
203 */
204typedef enum {
205 GST_NAVIGATION_MESSAGE_INVALID,
206 GST_NAVIGATION_MESSAGE_MOUSE_OVER,
207 GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED,
208 GST_NAVIGATION_MESSAGE_ANGLES_CHANGED,
209 GST_NAVIGATION_MESSAGE_EVENT
210} GstNavigationMessageType;
211
212GST_VIDEO_API
213GstNavigationMessageType gst_navigation_message_get_type (GstMessage *message);
214
215GST_VIDEO_API
216GstMessage * gst_navigation_message_new_mouse_over (GstObject *src,
217 gboolean active);
218
219GST_VIDEO_API
220gboolean gst_navigation_message_parse_mouse_over (GstMessage *message,
221 gboolean *active);
222
223GST_VIDEO_API
224GstMessage * gst_navigation_message_new_commands_changed (GstObject *src);
225
226GST_VIDEO_API
227GstMessage * gst_navigation_message_new_angles_changed (GstObject *src,
228 guint cur_angle,
229 guint n_angles);
230
231GST_VIDEO_API
232gboolean gst_navigation_message_parse_angles_changed (GstMessage *message,
233 guint *cur_angle,
234 guint *n_angles);
235
236GST_VIDEO_API
237GstMessage * gst_navigation_message_new_event (GstObject *src,
238 GstEvent *event);
239
240GST_VIDEO_API
241gboolean gst_navigation_message_parse_event (GstMessage *message,
242 GstEvent ** event);
243/* event parsing functions */
244/**
245 * GstNavigationEventType:
246 * @GST_NAVIGATION_EVENT_INVALID: Returned from
247 * gst_navigation_event_get_type() when the passed event is not a navigation event.
248 * @GST_NAVIGATION_EVENT_KEY_PRESS: A key press event. Use
249 * gst_navigation_event_parse_key_event() to extract the details from the event.
250 * @GST_NAVIGATION_EVENT_KEY_RELEASE: A key release event. Use
251 * gst_navigation_event_parse_key_event() to extract the details from the event.
252 * @GST_NAVIGATION_EVENT_MOUSE_BUTTON_PRESS: A mouse button press event. Use
253 * gst_navigation_event_parse_mouse_button_event() to extract the details from the
254 * event.
255 * @GST_NAVIGATION_EVENT_MOUSE_BUTTON_RELEASE: A mouse button release event. Use
256 * gst_navigation_event_parse_mouse_button_event() to extract the details from the
257 * event.
258 * @GST_NAVIGATION_EVENT_MOUSE_MOVE: A mouse movement event. Use
259 * gst_navigation_event_parse_mouse_move_event() to extract the details from the
260 * event.
261 * @GST_NAVIGATION_EVENT_COMMAND: A navigation command event. Use
262 * gst_navigation_event_parse_command() to extract the details from the event.
263 *
264 * Enum values for the various events that an element implementing the
265 * GstNavigation interface might send up the pipeline.
266 */
267typedef enum {
268 GST_NAVIGATION_EVENT_INVALID = 0,
269 GST_NAVIGATION_EVENT_KEY_PRESS = 1,
270 GST_NAVIGATION_EVENT_KEY_RELEASE = 2,
271 GST_NAVIGATION_EVENT_MOUSE_BUTTON_PRESS = 3,
272 GST_NAVIGATION_EVENT_MOUSE_BUTTON_RELEASE = 4,
273 GST_NAVIGATION_EVENT_MOUSE_MOVE = 5,
274 GST_NAVIGATION_EVENT_COMMAND = 6
275} GstNavigationEventType;
276
277GST_VIDEO_API
278GstNavigationEventType gst_navigation_event_get_type (GstEvent *event);
279
280GST_VIDEO_API
281gboolean gst_navigation_event_parse_key_event (GstEvent *event,
282 const gchar **key);
283
284GST_VIDEO_API
285gboolean gst_navigation_event_parse_mouse_button_event (GstEvent *event,
286 gint *button, gdouble *x, gdouble *y);
287
288GST_VIDEO_API
289gboolean gst_navigation_event_parse_mouse_move_event (GstEvent *event,
290 gdouble *x, gdouble *y);
291
292GST_VIDEO_API
293gboolean gst_navigation_event_parse_command (GstEvent *event,
294 GstNavigationCommand *command);
295
296/* interface virtual function wrappers */
297
298GST_VIDEO_API
299void gst_navigation_send_event (GstNavigation *navigation,
300 GstStructure *structure);
301
302GST_VIDEO_API
303void gst_navigation_send_key_event (GstNavigation *navigation,
304 const char *event, const char *key);
305
306GST_VIDEO_API
307void gst_navigation_send_mouse_event (GstNavigation *navigation,
308 const char *event, int button, double x, double y);
309
310GST_VIDEO_API
311void gst_navigation_send_command (GstNavigation *navigation,
312 GstNavigationCommand command);
313
314G_END_DECLS
315
316#endif /* __GST_NAVIGATION_H__ */
317