Added PJMEDIA_VID_DEV_CAP_SWITCH capability to allow fast switching to another device while the video device stream is running. Currently not implemented on any devices.(This closes #1362)

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@3781 74dad513-b988-da41-8d7b-12977e46ad98

2 files changed, 38 insertions, 1 deletions

diff --git a/pjmedia/include/pjmedia-videodev/videodev.h b/pjmedia/include/pjmedia-videodev/videodev.h
index 208b96c6..f64479d6 100644
--- a/pjmedia/include/pjmedia-videodev/videodev.h
+++ b/pjmedia/include/pjmedia-videodev/videodev.h
@@ -96,6 +96,20 @@ typedef struct pjmedia_vid_dev_hwnd
 } pjmedia_vid_dev_hwnd;
 
 /**
+ * Parameter for switching device with PJMEDIA_VID_DEV_CAP_SWITCH capability.
+ */
+typedef struct pjmedia_vid_dev_switch_param
+{
+    /**
+     * Target device ID to switch to. Once the switching is successful, the
+     * video stream will use this device and the old device will be closed.
+     */
+    pjmedia_vid_dev_index target_id;
+
+} pjmedia_vid_dev_switch_param;
+
+
+/**
  * Device index constants.
  */
 enum
@@ -206,6 +220,24 @@ typedef enum pjmedia_vid_dev_cap
     PJMEDIA_VID_DEV_CAP_ORIENTATION = 128,
 
     /**
+     * Support for fast switching to another device. A video stream with this
+     * capability allows replacing of its underlying device with another
+     * device, saving the user from opening a new video stream and gets a much
+     * faster and smoother switching action.
+     *
+     * Note that even when this capability is supported by a device, it may
+     * not be able to switch to arbitrary device. Application must always
+     * check the return value of the operation to verify that switching has
+     * occurred.
+     *
+     * This capability is currently write-only (i.e. set-only).
+     *
+     * The value of this capability is pointer to pjmedia_vid_dev_switch_param
+     * structure.
+     */
+    PJMEDIA_VID_DEV_CAP_SWITCH = 256,
+
+    /**
      * End of standard capability
      */
     PJMEDIA_VID_DEV_CAP_MAX = 16384
diff --git a/pjmedia/src/pjmedia-videodev/videodev.c b/pjmedia/src/pjmedia-videodev/videodev.c
index 6921f67b..6fc65966 100644
--- a/pjmedia/src/pjmedia-videodev/videodev.c
+++ b/pjmedia/src/pjmedia-videodev/videodev.c
@@ -45,7 +45,8 @@ static struct cap_info
     DEFINE_CAP("position",      "Renderer position"),
     DEFINE_CAP("hide",          "Renderer hide"),
     DEFINE_CAP("preview",       "Input preview"),
-    DEFINE_CAP("orientation",   "Video orientation")
+    DEFINE_CAP("orientation",   "Video orientation"),
+    DEFINE_CAP("switch",        "Switch device")
 };
 
 
@@ -183,6 +184,10 @@ static pj_status_t get_cap_pointer(const pjmedia_vid_dev_param *param,
     case PJMEDIA_VID_DEV_CAP_ORIENTATION:
 	FIELD_INFO(orient);
 	break;
+    /* The PJMEDIA_VID_DEV_CAP_SWITCH does not have an entry in the
+     * param (it doesn't make sense to open a stream and tell it
+     * to switch immediately).
+     */
     default:
 	return PJMEDIA_EVID_INVCAP;
     }