vidix/vidix.h

   1 /*
   2  * VIDIX - VIDeo Interface for *niX.
   3  *
   4  * This interface is introduced as universal one to MPEG decoder,
   5  * Back End Scaler (BES) and YUV2RGB hw accelerators.
   6  *
   7  * In the future it may be expanded up to capturing and audio things.
   8  * Main goal of this this interface imlpementation is providing DGA
   9  * everywhere where it's possible (unlike X11 and other).
  10  *
  11  * This interface is based on v4l2, fbvid.h, mga_vid.h projects
  12  * and my personal ideas.
  13  *
  14  * NOTE: This interface is introduced as driver interface.
  15  *
  16  * Copyright (C) 2002 Nick Kurshev
  17  * Copyright (C) 2007 Benjamin Zores <ben@geexbox.org>
  18  *
  19  * This file is part of MPlayer.
  20  *
  21  * MPlayer is free software; you can redistribute it and/or modify
  22  * it under the terms of the GNU General Public License as published by
  23  * the Free Software Foundation; either version 2 of the License, or
  24  * (at your option) any later version.
  25  *
  26  * MPlayer is distributed in the hope that it will be useful,
  27  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  28  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  29  * GNU General Public License for more details.
  30  *
  31  * You should have received a copy of the GNU General Public License along
  32  * with MPlayer; if not, write to the Free Software Foundation, Inc.,
  33  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  34  */
  35
  36 #ifndef MPLAYER_VIDIX_H
  37 #define MPLAYER_VIDIX_H
  38
  39 #define PROBE_NORMAL    0 /* normal probing */
  40 #define PROBE_FORCE     1 /* ignore device_id but recognize device if it's known */
  41
  42 typedef enum vidix_dev_type {
  43   TYPE_OUTPUT  =        0x00000000,     /* Is a video playback device */
  44   TYPE_CAPTURE =        0x00000001,     /* Is a capture device */
  45   TYPE_CODEC   =        0x00000002,     /* Device supports hw (de)coding */
  46   TYPE_FX      =        0x00000004,     /* Is a video effects device */
  47 } vidix_dev_type_t;
  48
  49 typedef enum vidix_dev_flag {
  50   FLAG_NONE       =     0x00000000, /* No flags defined */
  51   FLAG_DMA        =     0x00000001, /* Card can use DMA */
  52   /* Card can use DMA only if src pitch == dest pitch */
  53   FLAG_EQ_DMA     =     0x00000002,
  54   /* Possible to wait for DMA to finish. See BM_DMA_SYNC and BM_DMA_BLOCK */
  55   FLAG_SYNC_DMA   =     0x00000004,
  56   FLAG_UPSCALER   =     0x00000010, /* Card supports hw upscaling */
  57   FLAG_DOWNSCALER =     0x00000020, /* Card supports hw downscaling */
  58   FLAG_SUBPIC     =     0x00001000, /* Card supports DVD subpictures */
  59   FLAG_EQUALIZER  =     0x00002000, /* Card supports equalizer */
  60 } vidix_dev_flag_t;
  61
  62 typedef struct vidix_capability_s
  63 {
  64   char name[64]; /* Driver name */
  65   char author[64]; /* Author name */
  66   vidix_dev_type_t type;
  67   unsigned reserved0[4];
  68   int maxwidth;
  69   int maxheight;
  70   int minwidth;
  71   int minheight;
  72   int maxframerate; /* -1 if unlimited */
  73   vidix_dev_flag_t flags;
  74   unsigned short vendor_id;
  75   unsigned short device_id;
  76   unsigned reserved1[4];
  77 } vidix_capability_t;
  78
  79 typedef enum vidix_depth {
  80   VID_DEPTH_NONE  =             0x0000,
  81   VID_DEPTH_1BPP  =             0x0001,
  82   VID_DEPTH_2BPP  =             0x0002,
  83   VID_DEPTH_4BPP  =             0x0004,
  84   VID_DEPTH_8BPP  =             0x0008,
  85   VID_DEPTH_12BPP =             0x0010,
  86   VID_DEPTH_15BPP =             0x0020,
  87   VID_DEPTH_16BPP =             0x0040,
  88   VID_DEPTH_24BPP =             0x0080,
  89   VID_DEPTH_32BPP =             0x0100,
  90   VID_DEPTH_ALL   =             VID_DEPTH_1BPP  | VID_DEPTH_2BPP  | \
  91                                 VID_DEPTH_4BPP  | VID_DEPTH_8BPP  | \
  92                                 VID_DEPTH_12BPP | VID_DEPTH_15BPP | \
  93                                 VID_DEPTH_16BPP | VID_DEPTH_24BPP | \
  94                                 VID_DEPTH_32BPP,
  95 } vidix_depth_t;
  96
  97 typedef enum vidix_cap {
  98   VID_CAP_NONE               =  0x0000,
  99   /* if overlay can be bigger than source */
 100   VID_CAP_EXPAND             =  0x0001,
 101   /* if overlay can be smaller than source */
 102   VID_CAP_SHRINK             =  0x0002,
 103   /* if overlay can be blended with framebuffer */
 104   VID_CAP_BLEND              =  0x0004,
 105   /* if overlay can be restricted to a colorkey */
 106   VID_CAP_COLORKEY           =  0x0008,
 107   /* if overlay can be restricted to an alpha channel */
 108   VID_CAP_ALPHAKEY           =  0x0010,
 109   /* if the colorkey can be a range */
 110   VID_CAP_COLORKEY_ISRANGE   =  0x0020,
 111   /* if the alphakey can be a range */
 112   VID_CAP_ALPHAKEY_ISRANGE   =  0x0040,
 113   /* colorkey is checked against framebuffer */
 114   VID_CAP_COLORKEY_ISMAIN    =  0x0080,
 115   /* colorkey is checked against overlay */
 116   VID_CAP_COLORKEY_ISOVERLAY =  0x0100,
 117   /* alphakey is checked against framebuffer */
 118   VID_CAP_ALPHAKEY_ISMAIN    =  0x0200,
 119   /* alphakey is checked against overlay */
 120   VID_CAP_ALPHAKEY_ISOVERLAY =  0x0400,
 121 } vidix_cap_t;
 122
 123 typedef struct vidix_fourcc_s
 124 {
 125   unsigned fourcc;      /* input: requested fourcc */
 126   vidix_depth_t depth;  /* output: screen depth for given fourcc */
 127   vidix_cap_t flags;    /* output: capability */
 128 } vidix_fourcc_t;
 129
 130 typedef struct vidix_yuv_s
 131 {
 132   unsigned y,u,v;
 133 } vidix_yuv_t;
 134
 135 typedef struct vidix_rect_s
 136 {
 137   unsigned x,y,w,h;     /* in pixels */
 138   vidix_yuv_t pitch;    /* line-align in bytes */
 139 } vidix_rect_t;
 140
 141 typedef enum vidix_color_key_op {
 142   CKEY_FALSE =  0,
 143   CKEY_TRUE  =  1,
 144   CKEY_EQ    =  2,
 145   CKEY_NEQ   =  3,
 146   CKEY_ALPHA =  4,
 147 } vidix_color_key_op_t;
 148
 149 typedef struct vidix_color_key_s
 150 {
 151   vidix_color_key_op_t op;      /* defines logical operation */
 152   unsigned char red;
 153   unsigned char green;
 154   unsigned char blue;
 155   unsigned char reserved;
 156 }vidix_ckey_t;
 157
 158 typedef enum vidix_video_key_op {
 159   VKEY_FALSE =  0,
 160   VKEY_TRUE  =  1,
 161   VKEY_EQ    =  2,
 162   VKEY_NEQ   =  3,
 163 } vidix_video_key_op_t;
 164
 165 typedef struct vidix_video_key_s {
 166   vidix_video_key_op_t op;      /* defines logical operation */
 167   unsigned char key[8];
 168 } vidix_vkey_t;
 169
 170 typedef enum vidix_interleave {
 171   VID_PLAY_INTERLEAVED_UV =             0x00000001,
 172   /* UVUVUVUVUV used by Matrox G200 */
 173   INTERLEAVING_UV         =             0x00001000,
 174   /* VUVUVUVUVU */
 175   INTERLEAVING_VU         =             0x00001001,
 176 } vidix_interleave_t;
 177
 178 #define VID_PLAY_MAXFRAMES 64   /* unreal limitation */
 179
 180 typedef struct vidix_playback_s
 181 {
 182   unsigned fourcc;              /* app -> driver: movies's fourcc */
 183   unsigned capability;          /* app -> driver: what capability to use */
 184   unsigned blend_factor;        /* app -> driver: blending factor */
 185   vidix_rect_t src;             /* app -> driver: original movie size */
 186   vidix_rect_t dest;            /* app -> driver: destinition movie size.
 187                                    driver->app dest_pitch */
 188   vidix_interleave_t flags;     /* driver -> app: interleaved UV planes */
 189   /* memory model */
 190   unsigned frame_size;          /* driver -> app: destinition frame size */
 191   unsigned num_frames;          /* app -> driver: after call: driver -> app */
 192   unsigned offsets[VID_PLAY_MAXFRAMES]; /* driver -> app */
 193   vidix_yuv_t offset;           /* driver -> app: relative offsets
 194                                    within frame for yuv planes */
 195   void *dga_addr;               /* driver -> app: linear address */
 196 } vidix_playback_t;
 197
 198 typedef enum vidix_key_op {
 199   KEYS_PUT =    0,
 200   KEYS_AND =    1,
 201   KEYS_OR  =    2,
 202   KEYS_XOR =    3,
 203 } vidix_key_op_t;
 204
 205 typedef struct vidix_grkey_s
 206 {
 207   vidix_ckey_t ckey;            /* app -> driver: color key */
 208   vidix_vkey_t vkey;            /* app -> driver: video key */
 209   vidix_key_op_t key_op;        /* app -> driver: keys operations */
 210 } vidix_grkey_t;
 211
 212 typedef enum vidix_veq_cap {
 213   VEQ_CAP_NONE          =       0x00000000UL,
 214   VEQ_CAP_BRIGHTNESS    =       0x00000001UL,
 215   VEQ_CAP_CONTRAST      =       0x00000002UL,
 216   VEQ_CAP_SATURATION    =       0x00000004UL,
 217   VEQ_CAP_HUE           =       0x00000008UL,
 218   VEQ_CAP_RGB_INTENSITY =       0x00000010UL,
 219 } vidix_veq_cap_t;
 220
 221 typedef enum vidix_veq_flag {
 222   VEQ_FLG_ITU_R_BT_601 = 0x00000000, /* ITU-R BT.601 colour space (default) */
 223   VEQ_FLG_ITU_R_BT_709 = 0x00000001, /* ITU-R BT.709 colour space */
 224   VEQ_FLG_ITU_MASK     = 0x0000000f,
 225 } vidix_veq_flag_t;
 226
 227 typedef struct vidix_video_eq_s {
 228   vidix_veq_cap_t cap;   /* on get_eq should contain capability of
 229                             equalizer on set_eq should contain using fields */
 230   /* end-user app can have presets like: cold-normal-hot picture and so on */
 231   int brightness;               /* -1000 : +1000 */
 232   int contrast;                 /* -1000 : +1000 */
 233   int saturation;               /* -1000 : +1000 */
 234   int hue;                      /* -1000 : +1000 */
 235   int red_intensity;            /* -1000 : +1000 */
 236   int green_intensity;          /* -1000 : +1000 */
 237   int blue_intensity;           /* -1000 : +1000 */
 238   vidix_veq_flag_t flags;       /* currently specifies ITU YCrCb color
 239                                    space to use */
 240 } vidix_video_eq_t;
 241
 242 typedef enum vidix_interlace_flag {
 243   /* stream is not interlaced */
 244   CFG_NON_INTERLACED       =    0x00000000,
 245   /* stream is interlaced */
 246   CFG_INTERLACED           =    0x00000001,
 247   /* first frame contains even fields but second - odd */
 248   CFG_EVEN_ODD_INTERLACING =    0x00000002,
 249   /* first frame contains odd fields but second - even */
 250   CFG_ODD_EVEN_INTERLACING =    0x00000004,
 251   /* field deinterlace_pattern is valid */
 252   CFG_UNIQUE_INTERLACING   =    0x00000008,
 253   /* unknown deinterlacing - use adaptive if it's possible */
 254   CFG_UNKNOWN_INTERLACING  =    0x0000000f,
 255 } vidix_interlace_flag_t;
 256
 257 typedef struct vidix_deinterlace_s {
 258   vidix_interlace_flag_t flags;
 259   unsigned deinterlace_pattern; /* app -> driver: deinterlace pattern if
 260                                    flag CFG_UNIQUE_INTERLACING is set */
 261 } vidix_deinterlace_t;
 262
 263 typedef struct vidix_slice_s {
 264   void *address;                /* app -> driver */
 265   unsigned size;                /* app -> driver */
 266   vidix_rect_t slice;           /* app -> driver */
 267 } vidix_slice_t;
 268
 269 typedef enum vidix_bm_flag {
 270   LVO_DMA_NOSYNC             = 0,
 271   /* waits for vsync or hsync */
 272   LVO_DMA_SYNC               = 1,
 273 } vidix_dma_flag_t;
 274
 275 typedef struct vidix_dma_s
 276 {
 277   vidix_slice_t src;                    /* app -> driver */
 278   vidix_slice_t dest;                   /* app -> driver */
 279   vidix_dma_flag_t flags;               /* app -> driver */
 280 } vidix_dma_t;
 281
 282 typedef enum vidix_fx_type {
 283   FX_TYPE_BOOLEAN =             0x00000000,
 284   FX_TYPE_INTEGER =             0x00000001,
 285 } vidix_fx_type_t;
 286
 287 /*
 288    This structure is introdused to support OEM effects like:
 289    - sharpness
 290    - exposure
 291    - (auto)gain
 292    - H(V)flip
 293    - black level
 294    - white balance
 295    and many other
 296 */
 297 typedef struct vidix_oem_fx_s
 298 {
 299   vidix_fx_type_t type; /* type of effects */
 300   int num;              /* app -> driver: effect number.
 301                            From 0 to max number of effects */
 302   int minvalue;         /* min value of effect. 0 - for boolean */
 303   int maxvalue;         /* max value of effect. 1 - for boolean */
 304   int value;            /* current value of effect on get; required on set */
 305   char *name[80];       /* effect name to display */
 306 } vidix_oem_fx_t;
 307
 308 typedef struct VDXDriver {
 309   const char *name;
 310   struct VDXDriver *next;
 311   int (* probe) (int verbose, int force);
 312   int (* get_caps) (vidix_capability_t *cap);
 313   int (*query_fourcc)(vidix_fourcc_t *);
 314   int (*init)(void);
 315   void (*destroy)(void);
 316   int (*config_playback)(vidix_playback_t *);
 317   int (*playback_on)( void );
 318   int (*playback_off)( void );
 319   /* Functions below can be missed in driver ;) */
 320   int (*frame_sel)( unsigned frame_idx );
 321   int (*get_eq)( vidix_video_eq_t * );
 322   int (*set_eq)( const vidix_video_eq_t * );
 323   int (*get_deint)( vidix_deinterlace_t * );
 324   int (*set_deint)( const vidix_deinterlace_t * );
 325   int (*copy_frame)( const vidix_dma_t * );
 326   int (*get_gkey)( vidix_grkey_t * );
 327   int (*set_gkey)( const vidix_grkey_t * );
 328 } VDXDriver;
 329
 330 typedef struct VDXContext {
 331   VDXDriver *drv;
 332   /* might be filled in by much more info later on */
 333 } VDXContext;
 334
 335 /***************************************************************************/
 336 /*                              PUBLIC API                                 */
 337 /***************************************************************************/
 338
 339 /* Opens corresponded video driver and returns handle of associated stream.
 340  *   path - specifies path where drivers are located.
 341  *   name - specifies prefered driver name (can be NULL).
 342  *   cap  - specifies driver capability (TYPE_* constants).
 343  *   verbose - specifies verbose level
 344  * returns handle if ok else NULL.
 345  */
 346 VDXContext *vdlOpen (const char *name,unsigned cap,int verbose);
 347
 348 /* Closes stream and corresponded driver. */
 349 void vdlClose (VDXContext *ctx);
 350
 351 /* Queries driver capabilities. Return 0 if ok else errno */
 352 int vdlGetCapability (VDXContext *, vidix_capability_t *);
 353
 354 /* Queries support for given fourcc. Returns 0 if ok else errno */
 355 int vdlQueryFourcc (VDXContext *, vidix_fourcc_t *);
 356
 357 /* Returns 0 if ok else errno */
 358 int vdlConfigPlayback (VDXContext *, vidix_playback_t *);
 359
 360 /* Returns 0 if ok else errno */
 361 int vdlPlaybackOn (VDXContext *);
 362
 363 /* Returns 0 if ok else errno */
 364 int vdlPlaybackOff (VDXContext *);
 365
 366 /* Returns 0 if ok else errno */
 367 int vdlPlaybackFrameSelect (VDXContext *, unsigned frame_idx);
 368
 369 /* Returns 0 if ok else errno */
 370 int vdlGetGrKeys (VDXContext *, vidix_grkey_t *);
 371
 372 /* Returns 0 if ok else errno */
 373 int vdlSetGrKeys (VDXContext *, const vidix_grkey_t *);
 374
 375 /* Returns 0 if ok else errno */
 376 int vdlPlaybackGetEq (VDXContext *, vidix_video_eq_t *);
 377
 378 /* Returns 0 if ok else errno */
 379 int vdlPlaybackSetEq (VDXContext *, const vidix_video_eq_t *);
 380
 381 /* Returns 0 if ok else errno */
 382 int vdlPlaybackGetDeint (VDXContext *, vidix_deinterlace_t *);
 383
 384 /* Returns 0 if ok else errno */
 385 int vdlPlaybackSetDeint (VDXContext *, const vidix_deinterlace_t *);
 386
 387 /* Returns 0 if ok else errno */
 388 int vdlQueryNumOemEffects (VDXContext *, unsigned *number);
 389
 390 #endif /* MPLAYER_VIDIX_H */