From be8d37186b16150716f752883ae6857a0161db40 Mon Sep 17 00:00:00 2001
From: Benny Prijono <bennylp@teluu.com>
Date: Tue, 20 Sep 2011 10:07:55 +0000
Subject: Related to preview (re #1340): handle problems with starting or
 stopping preview during a call

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@3758 74dad513-b988-da41-8d7b-12977e46ad98
---
 pjmedia/include/pjmedia-videodev/videodev.h     | 42 +++++++++++++++++++++++--
 pjmedia/include/pjmedia-videodev/videodev_imp.h |  3 ++
 2 files changed, 43 insertions(+), 2 deletions(-)

(limited to 'pjmedia/include/pjmedia-videodev')

diff --git a/pjmedia/include/pjmedia-videodev/videodev.h b/pjmedia/include/pjmedia-videodev/videodev.h
index 30a9750b..0c3d4c82 100644
--- a/pjmedia/include/pjmedia-videodev/videodev.h
+++ b/pjmedia/include/pjmedia-videodev/videodev.h
@@ -220,7 +220,13 @@ typedef struct pjmedia_vid_dev_info
      */
     pjmedia_dir dir;
 
-    /** Specify whether the device supports callback */
+    /**
+     * Specify whether the device supports callback. Devices that implement
+     * "active interface" will actively call the callbacks to give or ask for
+     * video frames. If the device doesn't support callback, application
+     * must actively request or give video frames from/to the device by using
+     * pjmedia_vid_dev_stream_get_frame()/pjmedia_vid_dev_stream_put_frame().
+     */
     pj_bool_t has_callback;
 
     /** Device capabilities, as bitmask combination of #pjmedia_vid_dev_cap */
@@ -640,6 +646,16 @@ PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_set_cap(
 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_start(
 					    pjmedia_vid_dev_stream *strm);
 
+/**
+ * Query whether the stream has been started.
+ *
+ * @param strm	    The video stream
+ *
+ * @return	    PJ_TRUE if the video stream has been started.
+ */
+PJ_DECL(pj_bool_t) pjmedia_vid_dev_stream_is_running(pjmedia_vid_dev_stream *strm);
+
+
 /**
  * Get the event publisher object for the video stream. Caller typically use
  * the returned object to subscribe or unsubscribe events from the video
@@ -652,11 +668,33 @@ PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_start(
 PJ_DECL(pjmedia_event_publisher*)
 pjmedia_vid_dev_stream_get_event_publisher(pjmedia_vid_dev_stream *strm);
 
-/* Get/put frame API for passive stream */
+
+/**
+ * Request one frame from the stream. Application needs to call this function
+ * periodically only if the stream doesn't support "active interface", i.e.
+ * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
+ *
+ * @param strm      The video stream.
+ * @param frame	    The video frame to be filled by the device.
+ *
+ * @return          PJ_SUCCESS on successful operation or the appropriate
+ *                  error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_get_frame(
 					    pjmedia_vid_dev_stream *strm,
                                             pjmedia_frame *frame);
 
+/**
+ * Put one frame to the stream. Application needs to call this function
+ * periodically only if the stream doesn't support "active interface", i.e.
+ * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
+ *
+ * @param strm      The video stream.
+ * @param frame	    The video frame to put to the device.
+ *
+ * @return          PJ_SUCCESS on successful operation or the appropriate
+ *                  error code.
+ */
 PJ_DECL(pj_status_t) pjmedia_vid_dev_stream_put_frame(
 					    pjmedia_vid_dev_stream *strm,
                                             const pjmedia_frame *frame);
diff --git a/pjmedia/include/pjmedia-videodev/videodev_imp.h b/pjmedia/include/pjmedia-videodev/videodev_imp.h
index 90dcc580..8ddfd968 100644
--- a/pjmedia/include/pjmedia-videodev/videodev_imp.h
+++ b/pjmedia/include/pjmedia-videodev/videodev_imp.h
@@ -181,6 +181,9 @@ struct pjmedia_vid_dev_stream
     struct {
 	/** Driver index */
 	unsigned drv_idx;
+
+	/** Has it been started? */
+	pj_bool_t is_running;
     } sys;
 
     /** Operations */
-- 
cgit v1.2.3