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
