使用Gstreamer 作为数据源输出视频数据 III 填充数据

FillBufer及其逻辑

sourceFilter还有一个重要的工作就是生成数据，作为虚拟camera，他的数据由filter自己生成，并填充入buffer。这个工作有CSourceStream的fillbuffer来完成：

virtual HRESULT FillBuffer(
   IMediaSample *pSample
) = 0;

CSourceStream有一个DoBufferProcessingLoop 方法，这个方法实现了main loop的逻辑，用于处理数据和将数据传给下游。每一次循环，这个方法都会从allocator获取一个空的media sample，并把它传给 FillBuffer方法，FillBuffer方法负责生成数据，并将数据放入media sample，最终装入buffer中。

这个main loop一致循环，碰到下面三个条件的时候，会结束循环：

• 下游filter的input pin拒绝了一个sample(在IMemInputPin::Receive接口中拒绝)
• FillBuffer 返回S_FALSE，表示stream结束，或者错误返回错误码。
• 线程接收到 CSourceStream::Stop请求。

fillbuffer的返回码：

Return code	Description
S_FALSE	End of stream
S_OK	Success

在实现填充的时候还需要注意，pSample指向的media sample初始不含有时间戳。 fillbuffer方法的实现中需要通过IMediaSample::SetTime接口来设置这个时间戳。 对于有些媒体类型，也应该通过IMediaSample::SetMediaTime设置媒体时间。

IMediaSample接口

IMediaSample接口用来设置或者获取media sample的属性。 media sample是一个COM 对象， 它存储着meda data, 支持在filter间共享内存。我们使用IMediaSample来操作buffer, 填充数据。

• GetPointer 方法可以用来获取读写buffer的指针，media sample属于这个buffer。

HRESULT GetPointer(
  [out] BYTE **ppBuffer
);

一个buffer中包含一个或多个sample, sample 拥有由其所对应的的内存的控制权，所以填充数据需要通过sample的来获取开始指针。 当这个sample被销毁时，对应的内存也会被销毁。所以不要在外部通过指针重新分配或释放sample拥有的内存。

• GetActualDataLength 这个方法可以获得buffer中有效数据的长度。

long GetActualDataLength();

返回的有效长度以byte为单位。

• SetTime 用于设置当前sample的开始和结束时间

HRESULT SetTime(
  [in] REFERENCE_TIME *pTimeStart,  //指针指向当前meida sample的起始时间
  [in] REFERENCE_TIME *pTimeEnd   //指针指向当前meida sample的结束时间
);

这两个时间值是和媒体时间相对应的，可以理解为，sample包含了媒体时间轴上的一小段，这两个参数就是用来确认这一小段。 每次开始，重新播放，seek操作， 媒体的起始时间都会归0.

• SetMediaTime 设置当前sample的媒体时间
  HRESULT SetMediaTime(
  [in] LONGLONG *pTimeStart,
  [in] LONGLONG *pTimeEnd
  );
  这个时间可以用作计算媒体长度和sample的播放时间。
• SetSyncPoint

HRESULT SetSyncPoint(
  [in] BOOL bIsSyncPoint
);

这个接口用来确定sample的开始时间是否作为同步点。Source Filter在生成数据的时候需要设置这个标志。 对于未压缩的视频， 每一个sample都设置为ture. 对于压缩视频， 关键帧设置为true， delta frame设置为false.

sample 同步的时钟问题

DirectShow 定义了两者相关连的时钟： 参考时间 、 媒体时间
参考时间：它是绝对时间，由参考时钟（directshow中用于同步所有filter的时钟）获得。
媒体时间： 是值从最近一次播放开始点及时，所得的时间
* 播放器运行时, 媒体时间时间=参考时间 - 开始时间
* 播放器暂停时， 媒体时间时间=暂停时的媒体时间
* 当进行seek操作后， 媒体时间=0
* 当播放器停止时， 媒体时间=undefined
媒体时间主要用来计算图像应该被渲染的时间， 如果一个media sample有一个媒体时间t, 他就表示，这个media sample应该在媒体时间t 时被渲染。 所以媒体时间也叫做显示时间。
时间戳(time stamp)定义了一个 媒体sample的起始时间和结束时间, 这个时间使用媒体时间度量。所以在媒体开始播放的时间点，起始时间永远是0.
当播放器接收到一个sample, 他会根据时间戳来计划图像的渲染：如果sample抵达晚了或者没有时间戳，播放器将立刻渲染图像；否则，播放器需要等待sample的起始时间到达以后，在开始渲染。
Source filters 一般需要在sample上设置正确的时间戳。 另外, filter可以可选的为sample确定一个媒体时间. 在视频流中, media time 代表帧编号。

Fill buffer示例

下面给出一个FillBuffer的实现：

HRESULT CVCamStream::FillBuffer(IMediaSample *pms){
   REFERENCE_TIME rtNow;
    
    REFERENCE_TIME avgFrameTime = ((VIDEOINFOHEADER*)m_mt.pbFormat)->AvgTimePerFrame;  //获取每帧播放间隔

    rtNow = m_rtLastTime;  //获取上次计算的最后时间
    m_rtLastTime += avgFrameTime;  //计算本帧结束时间
    pms->SetTime(&rtNow, &m_rtLastTime);  //这只本真起始时间和结束时间
    pms->SetSyncPoint(TRUE);  //按本帧时间同步

    BYTE *pData;
    long lDataLen;
    pms->GetPointer(&pData);  //获取buffer数据块指针
   /***
      在本初填充真实数据
   ***/

    return NOERROR;
}

填充buffer，需要注意计算帧的起始时间和结束时间。

从gstappsink 获取数据

gstappsink插件对外提供了API，方面应用程序操作视频数据，我们可以通过这个接口获取来自gststreamer的数据，并将他作为数据源提供给directshow中的sourcefilter。
appsink提供了两种方式访问数据，一种是通过引入 gstappsink.h ，调用API方式访问； 定义中时使用gstreamer提供的信号机制，通过action信号和属性值来访问。

gstAppsink接口

API的方式提供了以下两类访问：

• gst_app_sink_pull_sample 和 gst_app_sink_pull_preroll
  gst_app_sink_pull_sample 只有当appsink在 PLAYING 状态的时候，返回sample, 并且请求一致会阻塞，直到返回一个sample或者EOF(表示媒体结束)， 当appsink在READY/NULL状态时也会迅速返回，且没有sample返回。

GstSample *
gst_app_sink_pull_sample ( * appsink)

需要注意的是，appsink维护着一个queue， 所有的buffer都会被放在这个queue里，所以应用程序可以按照自己的频率调用这个结构；另外，当应用程序消费的不够快，queue会占用很大的内存。
gst_app_sink_pull_preroll 用来从appsink获取最后一个preroll sample，这个方法用于处理pipleline在paused状态时获取一个preroll sample，或者发生seek的时候，调用给方法返回当前位置的sample.

GstSample *
gst_app_sink_pull_preroll( * appsink)

它也是会发生阻塞，知道返回一个sample或者EOF.

• gst_app_sink_try_pull_sample 和 gst_app_sink_try_pull_preroll
  gst_app_sink_try_pull_sample功能于gst_app_sink_pull_sample 相似，但是它不会长期阻塞。它有两个参数，第二个参数用于确定timeout的时间， 当请求长期阻塞并超过timeout的时间的时候，请求回结束等待并返回。

GstSample *
gst_app_sink_try_pull_sample ("GstAppSink") * appsink,
                              GstClockTime timeout)

gst_app_sink_try_pull_preroll 也是多了一个timeout参数，功能于gst_app_sink_pull_preroll接近，用于不长期阻塞场景。

GstSample *
gst_app_sink_try_pull_preroll ("GstAppSink") * appsink,
                              GstClockTime timeout)

当一个 EOS时间在获得buffer或timeout之前收到，上面的函数 都会返回NULL。需要使用 gst_app_sink_is_eos ()方法检查是否时流媒体结束了。

appsink内部使用queue从媒体流线程收集buffer，当pull sample比较慢时会发生占用大量内存的情况。我们可以使用"max-buffers"属性来限制queue的大小，同时使用"drop" 属性控制是否当queue达到最大长度时，可以将老buffer 丢弃掉。
appsink可以使用caps控制能够接收的格式，这个属性也可以是non-fixed caps， 通过pull获取的sample可以通过sample的getcap方法获取。

GstSample 结构

GstSample 是一个小对象，它包含了数据，类型，时间以及其它任意数据。它主要用来同应用程序交换buffer。使用gstappsink的方法gst_app_sink_pull_sample等可以获得 GstSample 对象。
GstSample 提供了以下方法

• gst_sample_get_buffer 获取sample中包含的buffer数据

GstBuffer *
gst_sample_get_buffer (GstSample * sample)

这个接口返回buffer或者NULL（当没有buffer的时候)。buffer的有效其和sample一样长。

• gst_sample_get_caps 获取sample的caps信息

GstCaps *
gst_sample_get_caps (GstSample * sample)

GstCap是一个描述媒体类型的对象，用于通过sample来获取实际媒体类型。

GstBuffer

冲区是 GStreamer 中数据传输的基本单元。它们包含了定时信息、偏移量信息、GstMemory，以及和GstMemory关联的任意元数据。
缓冲区通常是用 gst_buffer_new 创建的。创建缓冲区后，通常会为其分配内存并将其添加到缓冲区中。下面是创建一个缓冲区的示例，它可以容纳一个给定宽度、高度和像素深度（bpp）的视频帧。

GstBuffer *buffer;
  GstMemory *memory;
  gint size, width, height, bpp;
  ...
  size = width * height * bpp;
  buffer = gst_buffer_new ();
  memory = gst_allocator_alloc (NULL, size, NULL);
  gst_buffer_insert_memory (buffer, -1, memory);

可以看到，实际的视频数据存储在memory里。
缓冲区包含 的是GstMemory对象的列表。可以使用 gst_buffer_n_memory内存检索内存对象个，并且可以使用 gst_buffer_peek_memory获取 只想i一个内存的指针。
GstBuffer除了包含内存外，还可以包含几个重要的成员：

• pts (GstClockTime ）– buffer数据的显示时间

• dts (gstClockTime) – buffer数据的解码时间（处理时间）

• duration (GstClockTime) – buffer数据的播放持续时间

offset (guint64) – 媒体相关的偏移量，对于视频帧来说，他就是帧的编号。
可以看到buffer里存储的并不止我们需要的帧数据，可以通过以下方式获取我们想要的数据：
方法 1： 通过GST_BUFFER_DATA宏来获取

 raw = (gint16 *)GST_BUFFER_DATA (buffer);

方法 2：使用 gst_buffer_map() 和 gst_buffer_unmap() :
_map() 和 _unmap() 函数会返回一个大哥联系的block, 它包含了所以memery block的数据， 可以减少依次访问多个memery block的次数；但是因为需要进行memcpy操作，所以会降低性能。

GstMapInfo map;
gst_buffer_map (buffer, &map, GST_MAP_WRITE);
raw = (gint16 *)map.data;
  data->c += data->d;
  data->d -= data->c / 1000;
  freq = 1100 + 1000 * data->d;
  for (i = 0; i < num_samples; i++) {
    data->a += data->b;
    data->b -= data->a / freq;
    raw[i] = (gint16)(500 * data->a);
  }
  gst_buffer_unmap (buffer, &map);

方法三 通过gst_buffer_peek_memory 和gst_buffer_n_memory

GstMemory *
gst_buffer_peek_memory (GstBuffer * buffer,
                        guint idx)

gst_buffer_peek_memory 可以获得index id 为idx的memery block.

guint  
gst_buffer_n_memory( GstBuffer * buffer)

gst_buffer_n_memory 用来获取buffer中，memory的大小。
方法三中用到了GstMemory 结构，下来我们卡看这个结构。

GstMemory

GstMemory封装了 memory块. 用于GstBuffer的数据管理，每个buffer维护一个GstMemory数组。
GstMemory 被分配了块由maxsize确定的内存，它在整个声明周期中不可以改变大小。但它有一个offset属性和size属性，用来确定存储有效数据的内存区域。
通过方法gst_memory_map，我们可以访问GstMemory中的数据，这个方法会返回一个指向offset bytes位的指针，用来读取数据。当使用这个方法后，需要调用gst_memory_unmap方法，去除映射。

gboolean
gst_memory_map (GstMemory * mem,
                GstMapInfo * info,
                GstMapFlags flags)

info 是一个GstMapInfo指针，GstMapInfo 包含了map操作的结果，它包含由数据和大小，可以通过它访问以下它的成员信息：
memory (GstMemory *) – 指向所映射memory的指针

flags (GstMapFlags) – 用于map memory时的标志

data (guint8 *) – memory 包含数据的指针

size (gsize) – data的有效大小

maxsize (gsize) – data的最大字节数

user_data (gpointer *) – 用户额外存储的数据。
通常我们使用，info->data[i]来访问数据。

GstMemory *mem;
  GstMapInfo info;
  gint i;

  /* allocate 100 bytes */
  mem = gst_allocator_alloc (NULL, 100, NULL);

  /* get access to the memory in write mode */
  gst_memory_map (mem, &info, GST_MAP_WRITE);

  /* fill with pattern */
  for (i = 0; i < info.size; i++)
    info.data[i] = i;

  /* release memory */
  gst_memory_unmap (mem, &info);

GstMapFlags 的取值

GST_MAP_READ (1) – 只读访问
GST_MAP_WRITE (2) – 可写访问
GST_MAP_FLAG_LAST (65536) – first flag that can be used for custom purposes