Changeset 3663 for pjproject/branches/projects/2.0-dev/pjmedia/include/pjmedia/vid_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/vid_codec.h (modified) (12 diffs)

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

@@ -114 +114 @@
      * Initialize codec using the specified attribute.
      *
+     * Application should call #pjmedia_vid_codec_init() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param pool      Pool to use when the codec needs to allocate
@@ -130 +133 @@
      * preferences via SDP fmtp).
      *
+     * Application should call #pjmedia_vid_codec_open() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param param     Codec initialization parameter.
@@ -141 +147 @@
      * Close and shutdown codec, releasing all resources allocated by
      * this codec, if any.
+     *
+     * Application should call #pjmedia_vid_codec_close() instead of 
+     * calling this function directly.
      *
      * @param codec     The codec instance.
@@ -154 +163 @@
      * non-PJ_SUCCESS, and the original parameters will not be changed.
      *
+     * Application should call #pjmedia_vid_codec_modify() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param param     The new codec parameter.
@@ -164 +176 @@
     /** 
      * Get the codec parameter after the codec is opened. 
+     *
+     * Application should call #pjmedia_vid_codec_get_param() instead of 
+     * calling this function directly.
      *
      * @param codec     The codec instance.
@@ -181 +196 @@
      * performance reason, the packetization will be done in-place, so the
      * original bitstream may be modified by this function.
+     *
+     * Application should call #pjmedia_vid_codec_packetize() instead of 
+     * calling this function directly.
      *
      * @param codec     The codec instance
@@ -212 +230 @@
      * set to NULL, as the packetizer need to update its internal state.
      *
+     * Application should call #pjmedia_vid_codec_unpacketize() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance
      * @param pkt       The input packet.
@@ -236 +257 @@
      * in opening the codec.
      *
+     * Application should call #pjmedia_vid_codec_encode() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param input     The input frame.
@@ -257 +281 @@
      * using #get_param().
      *
+     * Application should call #pjmedia_vid_codec_decode() instead of 
+     * calling this function directly.
+     *
      * @param codec     The codec instance.
      * @param input     The input frame.
@@ -271 +298 @@
     /**
      * Instruct the codec to recover a missing frame.
+     *
+     * Application should call #pjmedia_vid_codec_recover() instead of 
+     * calling this function directly.
      *
      * @param codec     The codec instance.
@@ -433 +463 @@
  * @param sig       Codec's object signature (see signatures.h)
  */
-PJ_DECL(void) pjmedia_vid_codec_init(pjmedia_vid_codec *codec,
-                                     pjmedia_obj_sig sig);
+PJ_DECL(void) pjmedia_vid_codec_reset(pjmedia_vid_codec *codec,
+                                      pjmedia_obj_sig sig);
 
 /**
@@ -700 +730 @@
 
 
+/** 
+ * 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_vid_codec_init( pjmedia_vid_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 size or frame rate of
+ * the encoder format, as it may need to be negotiated with remote
+ * preferences via SDP fmtp).
+ *
+ * @param codec     The codec instance.
+ * @param param     Codec initialization parameter.
+ *
+ * @return          PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_vid_codec_open(
+                                            pjmedia_vid_codec *codec, 
+                                            pjmedia_vid_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_vid_codec_close( pjmedia_vid_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.
+ *
+ * @param codec The codec instance.
+ * @param param The new codec parameter.
+ *
+ * @return              PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_vid_codec_modify(
+                                    pjmedia_vid_codec *codec, 
+                                    const pjmedia_vid_codec_param *param)
+{
+    return (*codec->op->modify)(codec, param);
+}
+
+
+/** 
+ * Get the codec parameter after the codec is opened. 
+ *
+ * @param codec The codec instance.
+ * @param param The codec parameter.
+ *
+ * @return              PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_vid_codec_get_param(
+                                    pjmedia_vid_codec *codec, 
+                                    pjmedia_vid_codec_param *param)
+{
+    return (*codec->op->get_param)(codec, param);
+}
+
+
+/**
+ * Instruct the codec to generate a payload/packet from a picture
+ * bitstream to be sent (via network). The maximum payload size or
+ * MTU is configurable via enc_mtu field of #pjmedia_vid_codec_param.
+ * For a long bitstream, application usually need to call this function
+ * multiple times until the whole bitstream is sent. Note that, for
+ * performance reason, the packetization will be done in-place, so the
+ * original bitstream may be modified by this function.
+ *
+ * @param codec The codec instance
+ * @param bits  The picture bitstream.
+ * @param bits_len      The length of the bitstream.
+ * @param bits_pos      On input, the start position of the bitstream
+ *                      to be packetized. On output, the next position for
+ *                      next packet.
+ * @param pkt   The pointer of the generated payload.
+ * @param pkt_len       The payload length.
+ *
+ * @return              PJ_SUCCESS on success.
+ */
+PJ_INLINE(pj_status_t) pjmedia_vid_codec_packetize(
+                                            pjmedia_vid_codec *codec,
+                                            pj_uint8_t *bits,
+                                            pj_size_t bits_len,
+                                            unsigned *bits_pos,
+                                            const pj_uint8_t **pkt,
+                                            pj_size_t *pkt_len )
+{
+    return (*codec->op->packetize)(codec, bits, bits_len, bits_pos,
+                                   pkt, pkt_len);
+}
+
+
+/**
+ * Instruct the codec to parse a payload and append it into a picture
+ * bitstream. A picture bitstreams may need to be reconstructed from
+ * one or more payloads. Note that this function will not provide the
+ * detection of picture boundary, so application should manage the
+ * picture boundary detection by itself, e.g: for RTP delivery, payloads
+ * belong to the same picture will share the same RTP timestamp and also
+ * there is marker bit in the RTP header that is usually reserved for
+ * end-of-picture flag. Also note that in case of noticing packet lost,
+ * application should keep calling this function with payload pointer
+ * set to NULL, as the packetizer need to update its internal state.
+ *
+ * @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_vid_codec_unpacketize(
+                                                pjmedia_vid_codec *codec,
+                                                const pj_uint8_t *payload,
+                                                pj_size_t payload_len,
+                                                pj_uint8_t *bits,
+                                                pj_size_t bits_len,
+                                                unsigned *bits_pos )
+{
+    return (*codec->op->unpacketize)(codec, payload, payload_len, bits,
+                                     bits_len, bits_pos);
+}
+
+
+/** 
+ * Instruct the codec to encode the specified input frame. The input
+ * MUST contain only one picture with appropriate format as specified
+ * in opening the codec.
+ *
+ * @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_vid_codec_encode(
+                                            pjmedia_vid_codec *codec, 
+                                            const pjmedia_frame *input,
+                                            unsigned out_size, 
+                                            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 contain exactly one picture. Note that the decoded picture
+ * format may different to the current setting, e.g: the format specified
+ * in the #pjmedia_vid_codec_param when opening the codec, in this case the
+ * PJMEDIA_EVENT_FMT_CHANGED event will be emitted by the codec. The codec
+ * parameter will also be updated, and application can query the format by
+ * using #get_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_vid_codec_decode(
+                                            pjmedia_vid_codec *codec, 
+                                            const pjmedia_frame *input,
+                                            unsigned out_size, 
+                                            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_vid_codec_recover(
+                                            pjmedia_vid_codec *codec, 
+                                            unsigned out_size, 
+                                            pjmedia_frame *output)
+{
+    if (codec->op && codec->op->recover)
+        return (*codec->op->recover)(codec, out_size, output);
+    else
+        return PJ_ENOTSUP;
+}