include/realmedia/rmalvpix.h

   1 /****************************************************************************
   2  *
   3  *  rmalvpix.h
   4  *
   5  *  Copyright (C) 1995-1999 RealNetworks, Inc. All rights reserved.
   6  *
   7  *  http://www.real.com/devzone
   8  *
   9  *  This program contains proprietary
  10  *  information of Progressive Networks, Inc, and is licensed
  11  *  subject to restrictions on use and distribution.
  12  *
  13  *
  14  *  RealPix live encoder interfaces
  15  *
  16  */
  17
  18 #ifndef _RMALVPIX_H
  19 #define _RMALVPIX_H
  20
  21 /*
  22  * PixInitInfo
  23  *
  24  * This struct contains initialization information
  25  * and is passed in in the IRMALiveRealPix::StartEncoder()
  26  * method. All of the members of this struct are input variables.
  27  */
  28 typedef struct PNEXPORT_CLASS _PixInitInfo
  29 {
  30     UINT32  m_ulStructLength;       /* length in bytes of this structure */
  31     char   *m_pServerAddress;       /* name or ip address of server */
  32     UINT32  m_ulServerPort;         /* pn-encoder port on server */
  33     char   *m_pUsername;            /* username for authentication on server */
  34     char   *m_pPassword;            /* password for authentication on server */
  35     char   *m_pFilename;            /* filename which clients should open */
  36     char   *m_pTitle;               /* title of live presentation */
  37     char   *m_pAuthor;              /* author of live presentation */
  38     char   *m_pCopyright;           /* copyright on live presentation */
  39     UINT32  m_ulBitrate;            /* bitrate of realpix stream */
  40     UINT32  m_ulMaxFps;             /* max frames per second of effects */
  41     UINT32  m_ulDisplayWidth;       /* display width in pixels */
  42     UINT32  m_ulDisplayHeight;      /* display height in pixels */
  43     BOOL    m_bPreserveAspect;      /* preserve aspect ratio by default? */
  44     char   *m_pDefaultURL;          /* default URL to send browser to when clicked */
  45     UINT32  m_ulNumImageCodecs;     /* number of image codecs used in this stream */
  46     char  **m_ppImageCodec;         /* string names of codecs */
  47     UINT32  m_ulNumEffectPackages;  /* number of external effect packages used */
  48     char  **m_ppEffectPackage;      /* string names of effect packages*/
  49 }
  50 PixInitInfo;
  51
  52 /*
  53  * PixImageInfo
  54  *
  55  * This struct contains all the information for images which
  56  * should be sent down the stream. This struct is used in the
  57  * IRMALiveRealPix::InitImage() method.
  58  */
  59 typedef struct PNEXPORT_CLASS _PixImageInfo
  60 {
  61     UINT32  m_ulStructLength;      /* Input:  size of struct */
  62     BYTE   *m_pImageBuffer;        /* Input:  buffer holding image data */
  63     UINT32  m_ulImageBufferSize;   /* Input:  size of image buffer */
  64     char   *m_pImageCodec;         /* Input:  image codec to be used */
  65     UINT32  m_ulHandle;            /* Output: image handle */
  66     UINT32  m_ulNumPackets;        /* Output: number of packets image will be sent */
  67     UINT32  m_ulTimeToSend;        /* Output: milliseconds required to send image */
  68 }
  69 PixImageInfo;
  70
  71 #define EFFECT_FILL           0
  72 #define EFFECT_FADEIN         1
  73 #define EFFECT_FADEOUT        2
  74 #define EFFECT_CROSSFADE      3
  75 #define EFFECT_WIPE           4
  76 #define EFFECT_VIEWCHANGE     5
  77 #define EFFECT_EXTERNAL       6
  78 #define EFFECT_ANIMATE        7
  79
  80 #define WIPE_DIRECTION_UP     0
  81 #define WIPE_DIRECTION_DOWN   1
  82 #define WIPE_DIRECTION_LEFT   2
  83 #define WIPE_DIRECTION_RIGHT  3
  84
  85 #define WIPE_TYPE_NORMAL      0
  86 #define WIPE_TYPE_PUSH        1
  87
  88 /*
  89  * PixEffectInfo
  90  *
  91  * This struct contains all the information about the effect which
  92  * the RealPix renderer should perform. This struct is used in the
  93  * IRMALiveRealPix::SendEffect() method.
  94  */
  95 typedef struct PNEXPORT_CLASS _PixEffectInfo
  96 {
  97     UINT32  m_ulStructLength;      /* Input:  Length in bytes of this struct */
  98     BYTE    m_ucEffectType;        /* Input:  Effect Type: EFFECT_FILL, EFFECT_FADEIN, etc. */
  99     UINT32  m_ulStart;             /* Input:  Start time in milliseconds of effect */
 100     UINT32  m_ulDuration;          /* Input:  Duration in milliseconds of effect */
 101     UINT32  m_ulTarget;            /* Input:  Handle of image to perform effect on */
 102     UINT32  m_ulSrcX;              /* Input:  Horizontal offset of source rectangle */
 103     UINT32  m_ulSrcY;              /* Input:  Vertical offset of source rectangle */
 104     UINT32  m_ulSrcW;              /* Input:  Width of source rectangle */
 105     UINT32  m_ulSrcH;              /* Input:  Height of source rectangle */
 106     UINT32  m_ulDstX;              /* Input:  Horizontal offset of destination rectangle */
 107     UINT32  m_ulDstY;              /* Input:  Vertical offset of destination rectangle */
 108     UINT32  m_ulDstW;              /* Input:  Width of destination rectangle */
 109     UINT32  m_ulDstH;              /* Input:  Height of destination rectangle */
 110     UINT32  m_ulMaxFps;            /* Input:  Max frames per second for this effect */
 111     BOOL    m_bAspectFlag;         /* Input:  TRUE: preserve aspect on this effect; FALSE: don't preserve */
 112     BYTE    m_ucRed;               /* Input:  Red component of fill or fadeout color */
 113     BYTE    m_ucGreen;             /* Input:  Green component of fill or fadeout color */
 114     BYTE    m_ucBlue;              /* Input:  Blue component of fill or fadeout color */
 115     BYTE    m_ucWipeDirection;     /* Input:  WIPE_DIRECTION_xxx, where xxx is UP, DOWN, LEFT, or RIGHT */
 116     BYTE    m_ucWipeType;          /* Input:  WIPE_TYPE_NORMAL or WIPE_TYPE_PUSH */
 117     char   *m_pURL;                /* Input:  URL for this effect */
 118     char   *m_pExtPackage;         /* Input:  Name of external effect package */
 119     char   *m_pExtName;            /* Input:  Name of external effect within the package */
 120     char   *m_pExtData;            /* Input   Opaque string data for external effect */
 121     char   *m_pExtFile;            /* Input:  File contents of external effect data */
 122     BOOL    m_bDiscardImage;       /* Input:  TRUE: discard image after doing effect; FALSE: don't discard */
 123     BOOL    m_bDisplayImmediately; /* Input:  FALSE: obey start time; TRUE: do effect immediately */
 124         UINT32  m_ulHandle;            /* Output: Handle by which effect will be referred to */
 125 }
 126 PixEffectInfo;
 127
 128 /*
 129  * Forward declarations of some interfaces defined here.
 130  */
 131 typedef _INTERFACE IRMALiveRealPix         IRMALiveRealPix;
 132 typedef _INTERFACE IRMALiveRealPixResponse IRMALiveRealPixResponse;
 133 typedef _INTERFACE IRMALiveRealPixResend   IRMALiveRealPixResend;
 134
 135 /*
 136  * Forward declarations of interfaces used here
 137  */
 138 typedef _INTERFACE IRMAValues              IRMAValues;
 139
 140 /*
 141  * Declaration of the DLL entry point
 142  */
 143 STDAPI CreateLiveRealPix(IRMALiveRealPix **);
 144
 145 typedef PN_RESULT (PNEXPORT_PTR FPRMCREATELIVEREALPIX)(IRMALiveRealPix **ppLiveRealPix);
 146
 147 /****************************************************************************
 148  *
 149  *  Interface:
 150  *
 151  *  IRMALivePix
 152  *
 153  *  Purpose:
 154  *
 155  *  Asynchronous interface that allows an application to encode live RealPix
 156  *
 157  *  IID_IRMALiveRealPix:
 158  *
 159  *  {E7ADF466-477D-11d2-AA0C-0060972D23A7}
 160  *
 161  */
 162 DEFINE_GUID(IID_IRMALiveRealPix,  0xe7adf466, 0x477d, 0x11d2, 0xaa, 0xc, 0x0,
 163             0x60, 0x97, 0x2d, 0x23, 0xa7);
 164
 165 #undef  INTERFACE
 166 #define INTERFACE   IRMALiveRealPix
 167
 168 DECLARE_INTERFACE_(IRMALiveRealPix, IUnknown)
 169 {
 170     /*
 171      *  IUnknown methods
 172      */
 173     STDMETHOD(QueryInterface)      (THIS_ REFIID riid, void **ppvObj) PURE;
 174
 175     STDMETHOD_(ULONG,AddRef)     (THIS) PURE;
 176
 177     STDMETHOD_(ULONG,Release)    (THIS) PURE;
 178
 179     /*
 180      *  IRMALiveRealPix methods
 181      */
 182
 183     /*
 184      * StartEncoder() must be called before anything else and a pointer to
 185      * an IRMALiveRealPixResponse interface must be passed in. The encoder will
 186      * respond to this call asynchronously with IRMALiveRealPixResponse::EncoderStarted().
 187      */
 188     STDMETHOD(StartEncoder)        (THIS_ PixInitInfo             *pInitInfo,
 189                                           IRMALiveRealPixResponse *pResponse) PURE;
 190
 191     /*
 192      * InitImage() is called to prep an image for being sent. It returns several useful
 193      * pieces of information which the caller can make use of: the handle to refer to
 194      * the image in SendImage(), the number of packets this image will be broken up into,
 195      * and the time required to send this image in milliseconds. Note that InitImage()
 196      * simply breaks the image up into packets - nothing has been sent to the server yet.
 197      * This is not an asynchronous call - all processing has finished by the time this
 198      * call returns.
 199      */
 200     STDMETHOD(InitImage)           (THIS_ PixImageInfo *pImageInfo) PURE;
 201
 202     /*
 203      * SendImage() tranfers the all the packets for the image referred to by ulImageHandle
 204      * into the packet send queue. Further calls to Process() will result in these
 205      * packets being sent to the RealServer. When all the packets for this image have
 206      * been sent, the encoder will respond with IRMALiveRealPixResponse::ImageSent().
 207      */
 208     STDMETHOD(SendImage)           (THIS_ UINT32 ulImageHandle) PURE;
 209
 210     /*
 211      * SendEffect() creates an effect packet with the information contained in
 212      * the PixEffectInfo struct and immediately adds this packet to the packet
 213      * send queue. Further calls to Process() will result in this packet being
 214      * sent to the server. A handle is returned in the PixEffectInfo struct by
 215      * which this effect can later be identified. When the effect has been
 216      * sent to the server, the encoder will respond with
 217      * IRMALiveRealPixResponse::EffectSent().
 218      */
 219     STDMETHOD(SendEffect)          (THIS_ PixEffectInfo *pEffectInfo) PURE;
 220
 221     /*
 222      * StopEncoder() may be called at any time after calling StartEncoder().
 223      * This tells the encoder that no more images of effects are going to
 224      * be sent to the encoder. The encoder shuts down the connection to
 225      * the server and responds with IRMALiveRealPixResponse::EncoderStopped().
 226      */
 227     STDMETHOD(StopEncoder)         (THIS) PURE;
 228
 229     /*
 230      * GetTime() returns the time in milliseconds since the encoder library was initialized.
 231      */
 232     STDMETHOD_(UINT32, GetTime)    (THIS) PURE;
 233
 234     /*
 235      * Process() must be called in order to give the library time to send
 236      * packets to the server. It should be called very often in between SendImage()
 237      * and ImageSent(), as well as between SendEffect() and EffectSent(). Other
 238      * that these times, it should be called every 3-5 seconds.
 239      */
 240     STDMETHOD(Process)             (THIS) PURE;
 241 };
 242
 243 /****************************************************************************
 244  *
 245  *  Interface:
 246  *
 247  *  IRMALiveRealPixResponse
 248  *
 249  *  Purpose:
 250  *
 251  *  Asynchronous response interface that allows an application to
 252  *  encode live RealPix
 253  *
 254  *  IID_IRMALiveRealPixResponse:
 255  *
 256  *  {E7ADF46C-477D-11d2-AA0C-0060972D23A7}
 257  *
 258  */
 259 DEFINE_GUID(IID_IRMALiveRealPixResponse, 0xe7adf46c, 0x477d, 0x11d2, 0xaa, 0xc, 0x0,
 260             0x60, 0x97, 0x2d, 0x23, 0xa7);
 261
 262
 263 #undef  INTERFACE
 264 #define INTERFACE   IRMALiveRealPixResponse
 265
 266 DECLARE_INTERFACE_(IRMALiveRealPixResponse, IUnknown)
 267 {
 268     /*
 269      *  IUnknown methods
 270      */
 271     STDMETHOD(QueryInterface)      (THIS_ REFIID riid, void **ppvObj) PURE;
 272
 273     STDMETHOD_(ULONG,AddRef)     (THIS) PURE;
 274
 275     STDMETHOD_(ULONG,Release)    (THIS) PURE;
 276
 277     /*
 278      *  IRMALiveRealPixResponse methods
 279      */
 280
 281     /*
 282      * EncoderStarted() is the asynchronous response to StartEncoder(). The status
 283      * argument tells whether initializing the server was successful or not, and the pszHeaderString
 284      * argument returns the text string returned by the RealServer.
 285      */
 286     STDMETHOD(EncoderStarted)      (THIS_ PN_RESULT status, const char *pszHeaderString) PURE;
 287
 288     /*
 289      * ImageSent() is the asynchronous response to SendImage(). The ulImageHandle argument
 290      * identifies which image has just completed sending to the server, and the status
 291      * argument tells whether or not the send was successful or not.
 292      */
 293     STDMETHOD(ImageSent)           (THIS_ PN_RESULT status, UINT32 ulImageHandle) PURE;
 294
 295     /*
 296      * EffectSent() is the asynchronous response to SendEffect(). The ulEffectHandle argument
 297      * identifies which effect has just completed sending to the server, and the status
 298      * argument tells whether or not the send was successful or not.
 299      */
 300     STDMETHOD(EffectSent)          (THIS_ PN_RESULT status, UINT32 ulEffectHandle) PURE;
 301
 302     /*
 303      * EncoderStopped() is the asynchronous response to StopEncoder(). The status
 304      * argument tells whether or not the stopping of the encoder was successful.
 305      * If the status is PNR_OK, then the application can then shut down or turn
 306      * around and call StartEncoder() again.
 307      */
 308     STDMETHOD(EncoderStopped)      (THIS_ PN_RESULT status) PURE;
 309
 310     /*
 311      * ErrorOccurred() is called when the encoder receives an error from the RealServer.
 312      * Depending upon the severity of the error, the RealServer may then shut down
 313      * the encoder and an EncoderStopped() call would be made. Therefore, the
 314      * application should be ready to handle an EncoderStopped() call at any time.
 315      * If an error occurs, it's probably a good idea to call StopEncoder() and shut
 316      * down the encoder from the application side anyway.
 317      */
 318     STDMETHOD(ErrorOccurred)       (THIS_ const UINT8   unSeverity,
 319                                           const ULONG32 ulRMACode,
 320                                           const ULONG32 ulUserCode,
 321                                           const char   *pszUserString,
 322                                           const char   *pszMoreInfoURL) PURE;
 323 };
 324
 325 /****************************************************************************
 326  *
 327  *  Interface:
 328  *
 329  *  IRMALiveRealPixResend
 330  *
 331  *  Purpose:
 332  *
 333  *  Allows re-sending and releasing of images with IRMALiveRealPix
 334  *
 335  *  IID_IRMALiveRealPixResend:
 336  *
 337  *  {D814DA11-8B02-11D3-8AF3-00C0F030B4E5}
 338  */
 339 DEFINE_GUID(IID_IRMALiveRealPixResend, 0xd814da11, 0x8b02, 0x11d3, 0x8a, 0xfe, 0x0,
 340             0xc0, 0xf0, 0x30, 0xb4, 0xe5);
 341
 342
 343 #undef  INTERFACE
 344 #define INTERFACE   IRMALiveRealPixResend
 345
 346 DECLARE_INTERFACE_(IRMALiveRealPixResend, IUnknown)
 347 {
 348     /*
 349      *  IUnknown methods
 350      */
 351     STDMETHOD(QueryInterface)      (THIS_ REFIID riid, void** ppvObj) PURE;
 352
 353     STDMETHOD_(ULONG,AddRef)     (THIS) PURE;
 354
 355     STDMETHOD_(ULONG,Release)    (THIS) PURE;
 356
 357     /*
 358      *  IRMALiveRealPixResend methods
 359      */
 360
 361     /*
 362      * InitResend() informs the encoder that from now on, after an
 363      * image is sent with SendImage() it should not be discarded
 364      * but held in the encoder until ReleaseImage() is called().
 365      */
 366     STDMETHOD(InitResend)   (THIS_ IRMAValues* pOptions) PURE;
 367
 368     /*
 369      * ReleaseImage() informs the encoder that the application no longer
 370      * intends to call SendImage() on the image referenced by ulImageHandle
 371      * and that it can discard the image. Further calls to SendImage(x) will
 372      * return PNR_UNKNOWN_IMAGE after ReleaseImage(x) has been called.
 373      * ReleaseImage(x) will return PNR_UNKNOWN_IMAGE if x is an unknown handle.
 374      */
 375     STDMETHOD(ReleaseImage) (THIS_ UINT32 ulImageHandle) PURE;
 376
 377     /*
 378      * DumpAllQueuedPackets() clears any packets currently waiting to be
 379      * sent to the server. These packets were put on the send queue by
 380      * either IRMALiveRealPix::SendImage() or IRMALiveRealPix::SendEffect().
 381      */
 382     STDMETHOD(DumpAllQueuedPackets) (THIS) PURE;
 383 };
 384
 385 #endif