Changeset 3663 for pjproject/branches/projects/2.0-dev/pjmedia/include/pjmedia/codec.h

Timestamp:

Jul 15, 2011 10:19:59 AM (13 years ago)

Author:

nanang

Message:

Fix #1295: Added thin wrapper for audio and video codec operations.

File:

• pjproject/branches/projects/2.0-dev/pjmedia/include/pjmedia/codec.h (modified) (10 diffs)

pjproject/branches/projects/2.0-dev/pjmedia/include/pjmedia/codec.h

@@ -28 +28 @@
 
 #include <pjmedia/port.h>
+#include <pj/errno.h>
 #include <pj/list.h>
 #include <pj/pool.h>
@@ -324 +325 @@
      * Initialize codec using the specified attribute.
      *
+     * Application should call #pjmedia_codec_init() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param pool      Pool to use when the codec needs to allocate
@@ -339 +343 @@
      * encoder ptime is different than decoder ptime).
      *
+     * Application should call #pjmedia_codec_open() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param param     Codec initialization parameter.
@@ -350 +357 @@
      * Close and shutdown codec, releasing all resources allocated by
      * this codec, if any.
+     *
+     * Application should call #pjmedia_codec_close() instead of 
+     * calling this function directly.
      *
      * @param codec     The codec instance.
@@ -366 +376 @@
      * changing VAD setting to succeed.
      *
+     * Application should call #pjmedia_codec_modify() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param param     The new codec parameter.
@@ -379 +392 @@
      * have ptime that is equal to basic frame ptime (i.e. the value of
      * info.frm_ptime in #pjmedia_codec_param).
+     *
+     * Application should call #pjmedia_codec_parse() instead of 
+     * calling this function directly.
      *
      * @param codec     The codec instance
@@ -404 +420 @@
      * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).
      *
+     * Application should call #pjmedia_codec_encode() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param input     The input frame.
@@ -423 +442 @@
      * frames before decoding each frame.
      *
+     * Application should call #pjmedia_codec_decode() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param input     The input frame.
@@ -437 +459 @@
     /**
      * Instruct the codec to recover a missing frame.
+     *
+     * Application should call #pjmedia_codec_recover() instead of 
+     * calling this function directly.
      *
      * @param codec     The codec instance.
@@ -913 +938 @@
 
 
+/** 
+ * Initialize codec using the specified attribute.
+ *
+ * @param codec     The codec instance.
+ * @param pool      Pool to use when the codec needs to allocate some memory.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_codec_init( pjmedia_codec *codec, 
+                                           pj_pool_t *pool )
+{
+    return (*codec->op->init)(codec, pool);
+}
+
+
+/** 
+ * Open the codec and initialize with the specified parameter.
+ * Upon successful initialization, the codec may modify the parameter
+ * and fills in the unspecified values (such as enc_ptime, when
+ * encoder ptime is different than decoder ptime).
+ *
+ * @param codec     The codec instance.
+ * @param param     Codec initialization parameter.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_codec_open( pjmedia_codec *codec, 
+                                           pjmedia_codec_param *param )
+{
+    return (*codec->op->open)(codec, param);
+}
+
+
+/** 
+ * Close and shutdown codec, releasing all resources allocated by
+ * this codec, if any.
+ *
+ * @param codec     The codec instance.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_codec_close( pjmedia_codec *codec )
+{
+    return (*codec->op->close)(codec);
+}
+
+
+/** 
+ * Modify the codec parameter after the codec is open. 
+ * Note that not all codec parameters can be modified during run-time. 
+ * When the parameter cannot be changed, this function will return 
+ * non-PJ_SUCCESS, and the original parameters will not be changed.
+ *
+ * Application can expect changing trivial codec settings such as
+ * changing VAD setting to succeed.
+ *
+ * @param codec     The codec instance.
+ * @param param     The new codec parameter.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_codec_modify(pjmedia_codec *codec, 
+                                            const pjmedia_codec_param *param)
+{
+    return (*codec->op->modify)(codec, param);
+}
+
+
+/**
+ * Instruct the codec to inspect the specified payload/packet and
+ * split the packet into individual base frames. Each output frames will
+ * have ptime that is equal to basic frame ptime (i.e. the value of
+ * info.frm_ptime in #pjmedia_codec_param).
+ *
+ * @param codec     The codec instance
+ * @param pkt       The input packet.
+ * @param pkt_size  Size of the packet.
+ * @param timestamp The timestamp of the first sample in the packet.
+ * @param frame_cnt On input, specifies the maximum number of frames
+ *                  in the array. On output, the codec must fill
+ *                  with number of frames detected in the packet.
+ * @param frames    On output, specifies the frames that have been
+ *                  detected in the packet.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_codec_parse( pjmedia_codec *codec,
+                                            void *pkt,
+                                            pj_size_t pkt_size,
+                                            const pj_timestamp *timestamp,
+                                            unsigned *frame_cnt,
+                                            pjmedia_frame frames[] )
+{
+    return (*codec->op->parse)(codec, pkt, pkt_size, timestamp,
+                               frame_cnt, frames);
+}
+
+
+/** 
+ * Instruct the codec to encode the specified input frame. The input
+ * PCM samples MUST have ptime that is multiplication of base frame
+ * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).
+ *
+ * @param codec         The codec instance.
+ * @param input         The input frame.
+ * @param out_size      The length of buffer in the output frame.
+ * @param output        The output frame.
+ *
+ * @return              PJ_SUCCESS on success;
+ */
+PJ_INLINE(pj_status_t) pjmedia_codec_encode( 
+                                        pjmedia_codec *codec, 
+                                        const struct pjmedia_frame *input,
+                                        unsigned out_size, 
+                                        struct pjmedia_frame *output )
+{
+    return (*codec->op->encode)(codec, input, out_size, output);
+}
+
+
+/** 
+ * Instruct the codec to decode the specified input frame. The input
+ * frame MUST have ptime that is exactly equal to base frame
+ * ptime (i.e. the value of info.frm_ptime in #pjmedia_codec_param).
+ * Application can achieve this by parsing the packet into base
+ * frames before decoding each frame.
+ *
+ * @param codec         The codec instance.
+ * @param input         The input frame.
+ * @param out_size      The length of buffer in the output frame.
+ * @param output        The output frame.
+ *
+ * @return              PJ_SUCCESS on success;
+ */
+PJ_INLINE(pj_status_t) pjmedia_codec_decode( 
+                                        pjmedia_codec *codec, 
+                                        const struct pjmedia_frame *input,
+                                        unsigned out_size, 
+                                        struct pjmedia_frame *output )
+{
+    return (*codec->op->decode)(codec, input, out_size, output);
+}
+
+
+/**
+ * Instruct the codec to recover a missing frame.
+ *
+ * @param codec         The codec instance.
+ * @param out_size      The length of buffer in the output frame.
+ * @param output        The output frame where generated signal
+ *                      will be placed.
+ *
+ * @return              PJ_SUCCESS on success;
+ */
+PJ_INLINE(pj_status_t) pjmedia_codec_recover( pjmedia_codec *codec,
+                                              unsigned out_size,
+                                              struct pjmedia_frame *output )
+{
+    if (codec->op && codec->op->recover)
+        return (*codec->op->recover)(codec, out_size, output);
+    else
+        return PJ_ENOTSUP;
+}