gst-libs/gst/video/navigation.h

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