GstSample: GStreamer 1.0 Core Reference Manual

## GstSample GstSample — A media sample |

## Functions

GstBuffer * | gst_sample_get_buffer ()
GstBufferList * | gst_sample_get_buffer_list ()
GstCaps * | gst_sample_get_caps ()
const GstStructure * | gst_sample_get_info ()
GstSegment * | gst_sample_get_segment ()
void | gst_sample_set_buffer ()
void | gst_sample_set_buffer_list ()
void | gst_sample_set_caps ()
void | gst_sample_set_segment ()
gboolean | gst_sample_set_info ()
GstSample * | gst_sample_new ()
GstSample * | gst_sample_ref ()
void | gst_sample_unref ()
GstSample * | gst_sample_copy ()
#define | gst_sample_is_writable()
#define | gst_sample_make_writable()

## Types and Values

| GstSample

## Object Hierarchy

        GBoxed
        ╰── GstSample

## Includes

    #include <gst/gst.h>

## Description

A GstSample is a small object containing data, a type, timing and extra arbitrary information.

## Functions

### gst_sample_get_buffer ()

    GstBuffer *
    gst_sample_get_buffer (GstSample *sample);

Get the buffer associated with `sample`

#### Parameters

sample | a GstSample |

#### Returns

the buffer of `sample` or `NULL` when there is no buffer. The buffer remains valid as long as `sample` is valid. If you need to hold on to it for longer than that, take a ref to the buffer with `gst_buffer_ref()`.

[transfer none][nullable]

### gst_sample_get_buffer_list ()

    GstBufferList *
    gst_sample_get_buffer_list (GstSample *sample);

Get the buffer list associated with `sample`

#### Parameters

sample | a GstSample |

#### Returns

the buffer list of `sample` or `NULL` when there is no buffer list. The buffer list remains valid as long as `sample` is valid. If you need to hold on to it for longer than that, take a ref to the buffer list with `gst_mini_object_ref()`.

[transfer none][nullable]

Since: 1.6

### gst_sample_get_caps ()

    GstCaps *
    gst_sample_get_caps (GstSample *sample);

Get the caps associated with `sample`

#### Parameters

sample | a GstSample |

#### Returns

the caps of `sample` or `NULL` when there is no caps. The caps remain valid as long as `sample` is valid. If you need to hold on to the caps for longer than that, take a ref to the caps with `gst_caps_ref()`.

[transfer none][nullable]

### gst_sample_get_info ()

    const GstStructure *
    gst_sample_get_info (GstSample *sample);

Get extra information associated with `sample` .

#### Parameters

sample | a GstSample |

#### Returns

the extra info of `sample` . The info remains valid as long as `sample` is valid.

[transfer none][nullable]

### gst_sample_get_segment ()

    GstSegment *
    gst_sample_get_segment (GstSample *sample);

Get the segment associated with `sample`

#### Parameters

sample | a GstSample |

#### Returns

the segment of `sample` . The segment remains valid as long as `sample` is valid.

[transfer none]

### gst_sample_set_buffer ()

    void
    gst_sample_set_buffer (GstSample *sample,
                           GstBuffer *buffer);

Set the buffer associated with `sample` . `sample` must be writable.

#### Parameters

sample | A GstSample |
buffer | A GstBuffer. | [transfer none]

Since: 1.16

### gst_sample_set_buffer_list ()

    void
    gst_sample_set_buffer_list (GstSample *sample,
                                GstBufferList *buffer_list);

Set the buffer list associated with `sample` . `sample` must be writable.

#### Parameters

sample | a GstSample |
buffer_list | a GstBufferList |

Since: 1.6

### gst_sample_set_caps ()

    void
    gst_sample_set_caps (GstSample *sample,
                         GstCaps *caps);

Set the caps associated with `sample` . `sample` must be writable.

#### Parameters

sample | A GstSample |
caps | A GstCaps. | [transfer none]

Since: 1.16

### gst_sample_set_segment ()

    void
    gst_sample_set_segment (GstSample *sample,
                            const GstSegment *segment);

Set the segment associated with `sample` . `sample` must be writable.

#### Parameters

sample | A GstSample |
segment | A GstSegment. | [transfer none]

Since: 1.16

### gst_sample_set_info ()

    gboolean
    gst_sample_set_info (GstSample *sample,
                         GstStructure *info);

Set the info structure associated with `sample` . `sample` must be writable, and `info` must not have a parent set already.

#### Parameters

sample | A GstSample |
info | A GstStructure. | [transfer full]

Since: 1.16

### gst_sample_new ()

    GstSample *
    gst_sample_new (GstBuffer *buffer,
                    GstCaps *caps,
                    const GstSegment *segment,
                    GstStructure *info);

Create a new GstSample with the provided details.

Free-function: gst_sample_unref

#### Parameters

buffer | a GstBuffer, or `NULL`. | [transfer none][allow-none]
caps | a GstCaps, or `NULL`. | [transfer none][allow-none]
segment | a GstSegment, or `NULL`. | [transfer none][allow-none]
info | a GstStructure, or `NULL`. | [transfer full][allow-none]

#### Returns

the new GstSample. `gst_sample_unref()` after usage.

[transfer full]

### gst_sample_ref ()

    GstSample *
    gst_sample_ref (GstSample *sample);

Increases the refcount of the given sample by one.

#### Parameters

sample | a GstSample |

#### Returns

`sample` .

[transfer full]

### gst_sample_unref ()

    void
    gst_sample_unref (GstSample *sample);

Decreases the refcount of the sample. If the refcount reaches 0, the sample will be freed.

#### Parameters

sample | a GstSample. | [transfer full]

### gst_sample_copy ()

    GstSample *
    gst_sample_copy (const GstSample *buf);

Create a copy of the given sample. This will also make a newly allocated copy of the data the source sample contains.

#### Parameters

buf | a GstSample. |

#### Returns

a new copy of `buf` .

[transfer full]

Since: 1.2

### gst_sample_is_writable()

    #define         gst_sample_is_writable(sample)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (sample))

Tests if you can safely set the buffer and / or buffer list of `sample` .

#### Parameters

sample | A GstSample |

Since: 1.16

### gst_sample_make_writable()

    #define         gst_sample_make_writable(sample)   GST_SAMPLE_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (sample)))

Returns a writable copy of `sample` . If the source sample is already writable, this will simply return the same sample.

Use this function to ensure that a sample can be safely modified before making changes to it, for example before calling `gst_sample_set_buffer()`

If the reference count of the source sample `sample` is exactly one, the caller is the sole owner and this function will return the sample object unchanged.

If there is more than one reference on the object, a copy will be made using `gst_sample_copy()`. The passed-in `sample` will be unreffed in that case, and the caller will now own a reference to the new returned sample object.

In short, this function unrefs the sample in the argument and refs the sample that it returns. Don't access the argument after calling this function unless you have an additional reference to it.

#### Parameters

sample | A GstSample. | [transfer full]

#### Returns

a writable sample which may or may not be the same as `sample` .

[transfer full]

Since: 1.16

## Types and Values

### GstSample

    typedef struct _GstSample GstSample;

The opaque structure of a GstSample. A sample contains a typed memory block and the associated timing information. It is mainly used to exchange buffers with an application.

## See Also

GstBuffer, GstCaps, GstSegment