text: /* $Id: vid_port.h 5939 2019-03-05 06:23:02Z nanang $ */
  /*
   * Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
   *
   * This program is free software; you can redistribute it and/or modify
   * it under the terms of the GNU General Public License as published by
   * the Free Software Foundation; either version 2 of the License, or
   * (at your option) any later version.
   *
   * This program is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU General Public License for more details.
   *
   * You should have received a copy of the GNU General Public License
   * along with this program; if not, write to the Free Software
   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   */
  #ifndef __PJMEDIA_VIDPORT_H__
  #define __PJMEDIA_VIDPORT_H__
  
  /**
   * @file pjmedia/videoport.h Video media port
   * @brief Video media port
   */
  
  #include <pjmedia-videodev/videodev.h>
  #include <pjmedia/port.h>
  
  /**
   * @defgroup PJMEDIA_VIDEO_PORT Video media port
   * @ingroup PJMEDIA_PORT_CLOCK
   * @brief Video media port
   * @{
   */
  
  PJ_BEGIN_DECL
  
  /**
   * This structure describes the parameters to create a video port
   */
  typedef struct pjmedia_vid_port_param
  {
      /**
       * Video stream parameter.
       */
      pjmedia_vid_dev_param	vidparam;
  
      /**
       * Specify whether the video port should use active or passive interface.
       * If active interface is selected, the video port will perform as
       * a media clock, automatically calls pjmedia_port_get_frame() and
       * pjmedia_port_put_frame() of its slave port (depending on the direction
       * that is specified when opening the video stream). If passive interface
       * is selected, application can retrieve the media port of this video
       * port by calling pjmedia_vid_port_get_passive_port(), and subsequently
       * calls pjmedia_port_put_frame() or pjmedia_port_get_frame() to that
       * media port.
       *
       * Default: PJ_TRUE
       */
      pj_bool_t		active;
  
  } pjmedia_vid_port_param;
  
  /**
   * Opaque data type for video port.
   */
  typedef struct pjmedia_vid_port pjmedia_vid_port;
  
  /**
   * Initialize the parameter with the default values. Note that this typically
   * would only fill the structure to zeroes unless they have different default
   * values.
   *
   * @param prm	The parameter.
   */
  PJ_DECL(void) pjmedia_vid_port_param_default(pjmedia_vid_port_param *prm);
  
  /**
   * Create a video port with the specified parameter. When video port opens
   * the video stream with different parameter than the requested values in
   * the \a prm.vidparam argument, it will automatically do the necessary
   * conversion.
   *
   * @param pool		Pool to allocate memory from.
   * @param prm		The video port parameter.
   * @param p_vp		Pointer to receive the result.
   *
   * @return		PJ_SUCCESS if video port has been created
   * 			successfully, or the appropriate error code.
   */
  PJ_DECL(pj_status_t) pjmedia_vid_port_create(pj_pool_t *pool,
  					     const pjmedia_vid_port_param *prm,
  					     pjmedia_vid_port **p_vp);
  
  /**
   * Set the callbacks of the video port's underlying video stream.
   *
   * @param vid_port	The video port.
   * @param cb            Pointer to structure containing video stream
   *                      callbacks.
   * @param user_data     Arbitrary user data, which will be given back in the
   *                      callbacks.
   */
  PJ_DECL(void) pjmedia_vid_port_set_cb(pjmedia_vid_port *vid_port,
  				      const pjmedia_vid_dev_cb *cb,
                                        void *user_data);
  
  /**
   * Return the underlying video stream of the video port.
   *
   * @param vid_port	The video port.
   *
   * @return		The video stream.
   */
  PJ_DECL(pjmedia_vid_dev_stream*)
  pjmedia_vid_port_get_stream(pjmedia_vid_port *vid_port);
  
  /**
   * Return the (passive) media port of the video port. This operation
   * is only valid for video ports created with passive interface selected.
   * Retrieving the media port for active video ports may raise an
   * assertion.
   *
   *  @param vid_port	The video port.
   *
   *  @return		The media port instance, or NULL.
   */
  PJ_DECL(pjmedia_port*)
  pjmedia_vid_port_get_passive_port(pjmedia_vid_port *vid_port);
  
  /**
   * Get a clock source from the video port.
   *
   * @param vid_port  The video port.
   *
   * @return	    The clock source.
   */
  PJ_DECL(pjmedia_clock_src *)
  pjmedia_vid_port_get_clock_src( pjmedia_vid_port *vid_port );
  
  /**
   * Set a clock source for the video port.
   *
   * @param vid_port  The video port.
   * @param clocksrc  The clock source.
   *
   * @return	    PJ_SUCCESS on success or the appropriate error code.
   */
  PJ_DECL(pj_status_t)
  pjmedia_vid_port_set_clock_src( pjmedia_vid_port *vid_port,
                                  pjmedia_clock_src *clocksrc );
  
  /**
   * Subscribe media event notifications from the specified media port.
   * Sample use case is that renderer video port needs to monitor stream port
   * events so renderer can adjust its param whenever stream port detects
   * format change.
   *
   * @param vid_port	The video port.
   * @param port		The media port whose events to be monitored.
   *
   * @return		PJ_SUCCESS on success or the appropriate error code.
   */
  PJ_DECL(pj_status_t) pjmedia_vid_port_subscribe_event(
  						pjmedia_vid_port *vid_port,
  						pjmedia_port *port);
  
  /**
   * Connect the video port to a downstream (slave) media port. This operation
   * is only valid for video ports created with active interface selected.
   * Connecting a passive video port may raise an assertion.
   *
   * @param vid_port	The video port.
   * @param port		A downstream media port to be connected to
   * 			this video port.
   * @param destroy	Specify if the downstream media port should also be
   * 			destroyed by this video port when the video port
   * 			is destroyed.
   *
   * @return		PJ_SUCCESS on success or the appropriate error code.
   */
  PJ_DECL(pj_status_t) pjmedia_vid_port_connect(pjmedia_vid_port *vid_port,
  					      pjmedia_port *port,
  					      pj_bool_t destroy);
  
  /**
   * Disconnect the video port from its downstream (slave) media port, if any.
   * This operation is only valid for video ports created with active interface
   * selected, and assertion may be triggered if this is invoked on a passive
   * video port.
   *
   * @param vid_port	The video port.
   *
   * @return		PJ_SUCCESS on success or the appropriate error code.
   */
  PJ_DECL(pj_status_t) pjmedia_vid_port_disconnect(pjmedia_vid_port *vid_port);
  
  /**
   * Retrieve the media port currently connected as downstream media port of the
   * specified video port. This operation is only valid for video ports created
   * with active interface selected, and assertion may be triggered if this is
   * invoked on a passive video port.
   *
   * @param vid_port	The video port.
   *
   * @return		Media port currently connected to the video port,
   * 			if any.
   */
  PJ_DECL(pjmedia_port*)
  pjmedia_vid_port_get_connected_port(pjmedia_vid_port *vid_port);
  
  /**
   * Start the video port.
   *
   * @param vid_port	The video port.
   *
   * @return		PJ_SUCCESS on success or the appropriate error code.
   */
  PJ_DECL(pj_status_t) pjmedia_vid_port_start(pjmedia_vid_port *vid_port);
  
  /**
   * Query whether the video port has been started.
   *
   * @param vid_port	The video port.
   *
   * @return		PJ_TRUE if the video port has been started.
   */
  PJ_DECL(pj_bool_t) pjmedia_vid_port_is_running(pjmedia_vid_port *vid_port);
  
  /**
   * Stop the video port.
   *
   * @param vid_port	The video port.
   *
   * @return		PJ_SUCCESS on success or the appropriate error code.
   */
  PJ_DECL(pj_status_t) pjmedia_vid_port_stop(pjmedia_vid_port *vid_port);
  
  /**
   * Destroy the video port, along with its video stream. If the video port is
   * an active one, this may also destroy the downstream media port, if the
   * destroy flag is set when the media port is connected.
   *
   * @param vid_port	The video port.
   */
  PJ_DECL(void) pjmedia_vid_port_destroy(pjmedia_vid_port *vid_port);
  
  
  PJ_END_DECL
  
  /**
   * @}
   */
  
  #endif /* __PJMEDIA_VIDPORT_H__ */
  
  