/****************************************************************************
 * 
 *  $Id: rtapreviewsink.h,v 1.1 2002/04/24 01:51:11 rbunnage Exp $
 *
 *  Copyright ©2001 RealNetworks.
 *  All rights reserved.
 *
 *  http://www.real.com/devzone
 *
 *  This program contains proprietary information of RealNetworks, Inc., 
 *  and is licensed subject to restrictions on use and distribution.
 *
 *  This is the interface used to receive preview media samples.
 *
 */

#ifndef _PREVIEWSINK_H
#define _PREVIEWSINK_H

#include "rtabase.h"


/****************************************************************************
 * 
 *  Interface:
 *
 *	IRTAPreviewSink
 *
 *  Purpose:
 *	
 *  This is the interface used to receive preview media samples
 *   
 *  IID_IRTAInputPreviewControl:
 *
 *  {B9EE69F3-BE4F-4a9b-90D0-0FE318E4F58A}
 *
 *
 */
DEFINE_GUID(IID_IRTAPreviewSink, 
0xb9ee69f3, 0xbe4f, 0x4a9b, 0x90, 0xd0, 0xf, 0xe3, 0x18, 0xe4, 0xf5, 0x8a);


#undef  INTERFACE
#define INTERFACE   IRTAPreviewSink

DECLARE_INTERFACE_(IRTAPreviewSink, IUnknown)
{
    /***********************************************************************/
    /*
     *	IUnknown methods
     */
    STDMETHOD(QueryInterface)		(THIS_
					 REFIID riid,
					 void** ppvObj) PURE;

    STDMETHOD_(UINT32,AddRef)		(THIS) PURE;

    STDMETHOD_(UINT32,Release)		(THIS) PURE;

    /***********************************************************************/
    /*
     *	IRTAPreviewSink methods
     */

    /************************************************************************
     *	Method:
     *	    IRTAPreviewSink::OnFormatChanged
     *	Purpose:
     *	    This is called to indicate that the next sample sent via 
     *      this interface's OnSample() call is going to be with a different
     *      format.
     *  Parameters:
     *      pProps - this property bag is filled with the following
     *                properties.
     *          + kPropMediaFormat (string) Currently only 
     *            kValueMediaFormatUncompVideo or kValueMediaFormatUncompAudio
     *            is supported.
     *          + if (kPropMediaFormat == kValueMediaFormatUncompVideo)
     *            + kPropVideoFrameWidth (UINT32)
     *            + kPropVideoFrameHeight (UINT32)
     *            + kPropVideoColorFormat (UINT32) See rtaconstants.h for full
     *              list of valid color formats.
     *            + any other properties by the filter found immediately
     *              before the preview sink's registered location.
     *          + if (kPropMediaFormat == kValueMediaFormatUncompAudio)
     *            + any properties by the filter found immediately
     *              before the preview sink's registered location.
     */
     STDMETHOD(OnFormatChanged) (THIS_
                                IRTAPropertyBag* pProps) PURE;


    /************************************************************************
     *	Method:
     *	    IRTAPreviewSink::OnSample
     *	Purpose:
     *	    This is the method that is called when a new media sample is
     *      available.
     *  Parameters:
     *      pSample - the new sample
	 */
     STDMETHOD(OnSample) (THIS_
                         IRTAMediaSample* pSample) PURE;
};






/****************************************************************************
 * 
 *  Interface:
 *
 *	IRTAPreviewSinkControl
 *
 *  Purpose:
 *
 *  This interface used to register preview sinks. It is currently
 *  implemented by the IRTAInput object, and the xxxtb?
 *
 *  IID_IRTAPreviewSinkControl:
 *
 *  {F71A6355-0DD6-4f3f-ABC9-9A383258FBD0}
 *
 *
 */
DEFINE_GUID(IID_IRTAPreviewSinkControl, 
0xf71a6355, 0xdd6, 0x4f3f, 0xab, 0xc9, 0x9a, 0x38, 0x32, 0x58, 0xfb, 0xd0);

#undef  INTERFACE
#define INTERFACE   IRTAPreviewSinkControl

DECLARE_INTERFACE_(IRTAPreviewSinkControl, IUnknown)
{
    /***********************************************************************/
    /*
     *	IUnknown methods
     */
    STDMETHOD(QueryInterface)		(THIS_
					 REFIID riid,
					 void** ppvObj) PURE;

    STDMETHOD_(UINT32,AddRef)		(THIS) PURE;

    STDMETHOD_(UINT32,Release)		(THIS) PURE;


    /***********************************************************************/
    /*
     *	IRTAPreviewSinkControl methods
     */


    /************************************************************************
     *	Method:
     *	    IRTAPreviewSinkControl::GetOptimalSinkProperties
     *	Purpose:
     *        Method used to get the optimal (the least CPU instensive)
     *        properties to use when registering as a preview sink (by 
     *        calling AddSink). If this call is successful, the
     *        passed in property bag is filled with the relevant property
     *        info.  See below for description of the meaning for these
     *        parameters.
     *  Parameters:
     *      ppProps - Points to property bag that caller created that
     *                contains the following properties:
     *
     *          + kPropMediaFormat (string) Currently only 
     *            kValueMediaFormatUncompVideo or kValueMediaFormatUncompAudio
     *            is supported.
     *          + kPropPreviewSinkPosition (UINT32) This is the position in
     *            the prefilter chain for which the caller wishes to insert
     *            a sink. Valid values are kValueBeforeAllPrefilters,
     *            kValueAfterAllPrefilters, or kValueAfterCodec.
     *
     *                
     *                If successful, this method will add the following
     *                properties to the bag:
     *
     *          + if (kPropMediaFormat == kValueMediaFormatUncompVideo)
     *            + kPropVideoFrameWidth (UINT32)
     *            + kPropVideoFrameHeight (UINT32)
     *            + kPropVideoColorFormat (UINT32) See rtaconstants.h for full
     *              list of valid color formats.
     *            + any other properties by the filter found immediately
     *              before the preview sink's registered location.
     *          + if (kPropMediaFormat == kValueMediaFormatUncompAudio)
     *            + any properties by the filter found immediately
     *              before the preview sink's registered location.
     */

     STDMETHOD(GetOptimalSinkProperties) (THIS_
                                          IRTAPropertyBag** ppProps) PURE;

    /************************************************************************
     *	Method:
     *	    IRTAPreviewSinkControl::AddSink
     *	Purpose:
     *      Method used to register as a preview sink for samples. If this
     *      method return a success code, then as soon as encoding begins,
     *      caller will begin to receive media sample callsbacks (or if the
     *      sink is being added to input, samples will be received as soon
     *      as IRTAInputPreviewControl::Open() is called).
     *
     *      Once a preview sink has been added with a property bag, any 
     *      additional sinks that are added at the same location (location is
     *      determined by 'kPropPreviewSinkPosition' and 
     *      'kPropMediaFormat' values) will be refused unless the passed in
     *      property bag has the same values.
     *	Parameters:
     *      pSink - pointer to the sink interface which is to be called when
     *              new samples are available.
     *      pProps - property bag specifying the properties of the format
     *               which the caller wishes to receive. Currently, setting
     *               properties here that differ from the SDK's internal
     *               format (which can be gotten via 
     *               'GetOptimalSinkProperties' method) will just be ignored
     *               However, eventually they will do any necessary color
     *               converts or resizing.
     *
     *          Here is the list of properties that can be set in the bag:
     *          + kPropMediaFormat (string) Currently only 
     *            kValueMediaFormatUncompVideo or kValueMediaFormatUncompAudio
     *            is supported.
     *          + kPropPreviewSinkPosition (UINT32) This is the position in
     *            the prefilter chain for which the caller wishes to insert
     *            a sink. Valid values are kValueBeforeAllPrefilters,
     *            kValueAfterAllPrefilters, or kValueAfterCodec.
     *          + kPropSinkUpdateInterval (INT32) This how often, in MS stream
     *            time, that the caller wishes to receive a sample. Valid 
     *            values are kValueFirstSample, kValueAllSamples, or an INT32
     *            specifying the time in MS between calls.
     *          + if (kPropMediaFormat == kValueMediaFormatUncompVideo)
     *            + kPropVideoFrameWidth (UINT32)
     *            + kPropVideoFrameHeight (UINT32)
     *            + kPropVideoColorFormat (UINT32) See rtaconstants.h for full
     *              list of valid color formats.
     * 
     *              NOTE: currently kPropVideoFrameWidth, kPropVideoFrameHeight
     *                    and kPropVideoColorFormat are ignored by the SDK.
     *
     *            + any other properties set will be ignored
     *          + if (kPropMediaFormat == kValueMediaFormatUncompAudio)
     *            + any other properties set will be ignored
     *
     */
     STDMETHOD(AddSink) (THIS_
                         IRTAPreviewSink* pSink, IRTAPropertyBag* pProps) PURE;


    /************************************************************************
     *	Method:
     *	    IRTAPreviewSinkControl::RemoveSink
     *	Purpose:
     *       Method used to unregister preview sink so that samples will no
     *       longer be sent to the passed sink.
     *  Parameters:
     *      pSink - the pointer to the sink which the caller wishes to remove
     */
     STDMETHOD(RemoveSink) (THIS_
                            IRTAPreviewSink* pSink) PURE;
};



/****************************************************************************
 * 
 *  Interface:
 *
 *	IRTAInputPreviewControl
 *
 *  Purpose:
 *
 *  This interface used to start and stop preview of an input.
 *
 *  IID_IRTAInputPreviewControl:
 *
 *  {5851036C-C40D-4ff6-BB02-3EA73F291516}
 *
 *
 */
DEFINE_GUID(IID_IRTAInputPreviewControl, 
0x5851036c, 0xc40d, 0x4ff6, 0xbb, 0x2, 0x3e, 0xa7, 0x3f, 0x29, 0x15, 0x16);

#undef INTERFACE
#define INTERFACE	IRTAInputPreviewControl

DECLARE_INTERFACE_(IRTAInputPreviewControl, IUnknown)
{
    /***********************************************************************/
    /*
     *	IUnknown methods
     */
    STDMETHOD(QueryInterface)		(THIS_
					 REFIID riid,
					 void** ppvObj) PURE;

    STDMETHOD_(UINT32,AddRef)		(THIS) PURE;

    STDMETHOD_(UINT32,Release)		(THIS) PURE;


    /***********************************************************************/
    /*
     *	IRTAInputPreviewControl methods
     */
 	
    /************************************************************************
     *	Method:
     *	    IRTAInputPreviewControl::Open
     *	Purpose:
     *	    Builds the input graph for the purposes of preview and begins
	 *		passing samples to registered sinks.
     */
    STDMETHOD (Open) (THIS) PURE;

    /************************************************************************
     *	Method:
     *	    IRTAInputPreviewControl::Close
     *	Purpose:
     *	    Stops passing media samples to the all registered sinks and
     *      tears down the input graph
     */
     STDMETHOD (Close) (THIS) PURE;
};



#endif _PREVIEWSINK_H