mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-23 16:50:47 +00:00
Code Issues 1 Projects Releases Wiki Activity

design/buffer: add missing markup

Browse source 
Drop some weird line-breaks and fix minor grammar issues while at it.
This commit is contained in:
Reynaldo H. Verdejo Pinochet 2016-12-20 20:55:26 -08:00
parent 41fabc4a5e
commit 849985ba7e
1 changed files with 14 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
markdown/design/buffer.md
View file

@ -2,7 +2,7 @@
This document describes the design for buffers.
A GstBuffer is the object that is passed from an upstream element to a
A `GstBuffer` is the object that is passed from an upstream element to a
downstream element and contains memory and metadata information.
## Requirements
@ -15,16 +15,16 @@ downstream element and contains memory and metadata information.
## Lifecycle
GstMemory extends from GstMiniObject and therefore uses its lifecycle
`GstMemory` extends from `GstMiniObject` and therefore uses its lifecycle
management (See [miniobject](design/miniobject.md)).
## Writability
When a Buffers is writable as returned from `gst_buffer_is_writable()`:
When a `GstBuffer` is writable as returned by `gst_buffer_is_writable()`:
- metadata can be added/removed and the metadata can be changed
- GstMemory blocks can be added/removed
- `GstMemory` blocks can be added/removed
The individual memory blocks have their own locking and READONLY flags
that might influence their writability.
@ -36,22 +36,22 @@ copying buffers.
# Managing GstMemory
A GstBuffer contains an array of pointers to GstMemory objects.
A `GstBuffer` contains an array of pointers to `GstMemory` objects.
When the buffer is writable, `gst_buffer_insert_memory()` can be used
to add a new GstMemory object to the buffer. When the array of memory is
to add a new `GstMemory` object to the buffer. When the array of memory is
full, memory will be merged to make room for the new memory object.
`gst_buffer_n_memory()` is used to get the amount of memory blocks on
the `GstBuffer`.
With `gst_buffer_peek_memory(),` memory can be retrieved from the
With `gst_buffer_peek_memory()`, memory can be retrieved from the
memory array. The desired access pattern for the memory block should be
specified so that appropriate checks can be made and, in case of
`GST_MAP_WRITE`, a writable copy can be constructed when needed.
`gst_buffer_remove_memory_range()` and `gst_buffer_remove_memory()`
can be used to remove memory from the GstBuffer.
can be used to remove memory from the `GstBuffer`.
# Subbuffers
@ -60,13 +60,12 @@ copying all of the metadata.
# Span
Spanning will merge together the data of 2 buffers into a new
buffer
Spanning will merge together the data of 2 buffers into a new buffer
# Data access
Accessing the data of the buffer can happen by retrieving the individual
GstMemory objects in the GstBuffer or by using the `gst_buffer_map()` and
`GstMemory` objects in the `GstBuffer` or by using the `gst_buffer_map()` and
`gst_buffer_unmap()` functions.
The `_map` and `_unmap` functions will always return the memory of all blocks as
@ -74,7 +73,7 @@ one large contiguous region of memory. Using the `_map` and `_unmap` functions
might be more convenient than accessing the individual memory blocks at the
expense of being more expensive because it might perform memcpy operations.
For buffers with only one GstMemory object (the most common case), `_map` and
For buffers with only one `GstMemory` object (the most common case), `_map` and
`_unmap` have no performance penalty at all.
- **Read access with 1 memory block**: The memory block is accessed and mapped
@ -103,11 +102,10 @@ then mapped in write mode and unmapped after usage.
## Generating RTP packets from h264 video
We receive as input a GstBuffer with an encoded h264 image and we need
We receive as input a `GstBuffer` with an encoded h264 image and we need
to create RTP packets containing this h264 data as the payload. We
typically need to fragment the h264 data into multiple packets, each
with their own RTP and payload specific
header.
with their own RTP and payload specific header.
```
+-------+-------+---------------------------+--------+
@ -126,7 +124,7 @@ output buffers: | | | NALU1 | | | | NALU2 | .... | | | NALUx |
The output buffer array consists of x buffers consisting of an RTP
payload header and a subbuffer of the original input H264 buffer. Since
the rtp headers and the h264 data don’t need to be contiguous in memory,
they are added to the buffer as separate GstMemory blocks and we can
they are added to the buffer as separate `GstMemory` blocks and we can
avoid to memcpy the h264 data into contiguous memory.
A typical udpsink will then use something like sendmsg to send the