# FrameSampler

<a id="framesampler"></a>

# FrameSampler

```cpp
#include <icy/vision/framesampler.h>

class FrameSampler
```

[Defined in src/vision/include/icy/vision/framesampler.h:52](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L52)

> **Inherits:** [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor)

[PacketProcessor](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) that forwards a sampled subset of decoded video frames.

The sampler is intentionally zero-copy on its synchronous path: sampled frames are forwarded by reference and dropped frames are discarded before any queue hop. Pair it with [DetectionQueue](https://auscaster.com/icey/docs/api-reference/icy-vision-DetectionQueue.md#detectionqueue) when a worker-thread boundary is required.

## List of all members

| Name | Kind | Owner |
|------|------|-------|
| [`emitter`](#emitter-14) | `variable` | Declared here |
| [`FrameSampler`](#framesampler-1) | `function` | Declared here |
| [`setConfig`](#setconfig-2) | `function` | Declared here |
| [`config`](#config-3) | `function` | Declared here |
| [`stats`](#stats-2) | `function` | Declared here |
| [`reset`](#reset-27) | `function` | Declared here |
| [`process`](#process-20) | `function` | Declared here |
| [`accepts`](#accepts-7) | `function` | Declared here |
| [`_config`](#_config-2) | `variable` | Declared here |
| [`_seen`](#_seen-2) | `variable` | Declared here |
| [`_forwarded`](#_forwarded) | `variable` | Declared here |
| [`_dropped`](#_dropped-2) | `variable` | Declared here |
| [`_lastForwardedTimeUsec`](#_lastforwardedtimeusec) | `variable` | Declared here |
| [`shouldForward`](#shouldforward) | `function` | Declared here |
| [`kUnsetTimeUsec`](#kunsettimeusec) | `variable` | Declared here |
| [`sanitize`](#sanitize-2) | `function` | Declared here |
| [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor-1) | `function` | Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) |
| [`process`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#process-1) | `function` | Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) |
| [`accepts`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#accepts-1) | `function` | Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) |
| [`operator<<`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#operator-69) | `function` | Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`~PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-2) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-2) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-3) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-4) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-5) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`getEmitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#getemitter) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`retention`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`_emitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#_emitter) | `variable` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-3) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-72) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-4) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |
| [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-73) | `function` | Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter) |

## Inherited from [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`PacketProcessor`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#packetprocessor-1) `inline` |  |
| `function` | [`process`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#process-1) `virtual` | This method performs processing on the given packet and emits the result. |
| `function` | [`accepts`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#accepts-1) `virtual` `inline` | This method ensures compatibility with the given packet type. Return false to reject the packet. |
| `function` | [`operator<<`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#operator-69) `virtual` `inline` | [Stream](https://auscaster.com/icey/docs/api-reference/icy-Stream.md#stream) operator alias for [process()](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#process-1) |

## Inherited from [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter)

| Kind | Name | Description |
|------|------|-------------|
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-1)  | Construct the adapter, binding it to the given packet signal. |
| `function` | [`~PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-2) `virtual` `inline` |  |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-1) `virtual` | Emit a mutable raw buffer as a packet. |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-2) `virtual` | Emit a read-only raw buffer as a packet (data is copied internally). |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-3) `virtual` | Emit a string as a packet (data is copied internally). |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-4) `virtual` | Emit a flag-only packet carrying no payload data. |
| `function` | [`emit`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#emit-5) `virtual` | Emit an existing packet directly onto the outgoing signal. |
| `function` | [`getEmitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#getemitter)  | Returns a reference to the outgoing packet signal. |
| `function` | [`retention`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1) `virtual` `const` | Returns how this adapter treats incoming packet lifetime. Most adapters are synchronous and therefore only borrow the packet for the current call chain. Queue-style adapters override this to advertise that they clone before deferred use. Callers may treat the first adapter reporting Cloned or Retained as the explicit ownership boundary in the stream graph. |
| `function` | [`onStreamStateChange`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#onstreamstatechange-1) `virtual` `inline` | Called by the [PacketStream](https://auscaster.com/icey/docs/api-reference/icy-PacketStream.md#packetstream) to notify when the internal [Stream](https://auscaster.com/icey/docs/api-reference/icy-Stream.md#stream) state changes. On receiving the Stopped state, it is the responsibility of the adapter to have ceased all outgoing packet transmission, especially in multi-thread scenarios. |
| `variable` | [`_emitter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#_emitter)  |  |
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-3)  | NonCopyable and NonMovable. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-72)  | Deleted assignment operator. |
| `function` | [`PacketStreamAdapter`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#packetstreamadapter-4)  | Deleted constructor. |
| `function` | [`operator=`](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#operator-73)  | Deleted assignment operator. |

## Public Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal) | [`emitter`](#emitter-14)  |  |

---

<a id="emitter-14"></a>

### emitter

```cpp
PacketSignal emitter
```

Type: [`PacketSignal`](https://auscaster.com/icey/docs/api-reference/base.md#packetsignal)

[Defined in src/vision/include/icy/vision/framesampler.h:55](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L55)

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`FrameSampler`](#framesampler-1) `inline` `explicit` |  |
| `void` | [`setConfig`](#setconfig-2) `inline` |  |
| [`FrameSamplerConfig`](https://auscaster.com/icey/docs/api-reference/icy-vision-FrameSamplerConfig.md#framesamplerconfig) | [`config`](#config-3) `const` `inline` |  |
| [`FrameSamplerStats`](https://auscaster.com/icey/docs/api-reference/icy-vision-FrameSamplerStats.md#framesamplerstats) | [`stats`](#stats-2) `const` `inline` |  |
| `void` | [`reset`](#reset-27) `inline` |  |
| `void` | [`process`](#process-20) `virtual` `inline` `override` | This method performs processing on the given packet and emits the result. |
| `bool` | [`accepts`](#accepts-7) `virtual` `inline` `override` | This method ensures compatibility with the given packet type. Return false to reject the packet. |

---

<a id="framesampler-1"></a>

### FrameSampler

`inline` `explicit`

```cpp
inline explicit FrameSampler(FrameSamplerConfig config = {})
```

[Defined in src/vision/include/icy/vision/framesampler.h:57](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L57)

---

<a id="setconfig-2"></a>

### setConfig

`inline`

```cpp
inline void setConfig(FrameSamplerConfig config)
```

[Defined in src/vision/include/icy/vision/framesampler.h:63](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L63)

---

<a id="config-3"></a>

### config

`const` `inline`

```cpp
inline FrameSamplerConfig config() const
```

[Defined in src/vision/include/icy/vision/framesampler.h:69](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L69)

---

<a id="stats-2"></a>

### stats

`const` `inline`

```cpp
inline FrameSamplerStats stats() const
```

[Defined in src/vision/include/icy/vision/framesampler.h:74](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L74)

---

<a id="reset-27"></a>

### reset

`inline`

```cpp
inline void reset()
```

[Defined in src/vision/include/icy/vision/framesampler.h:83](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L83)

---

<a id="process-20"></a>

### process

`virtual` `inline` `override`

```cpp
virtual inline void process(IPacket & packet) override
```

[Defined in src/vision/include/icy/vision/framesampler.h:91](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L91)

This method performs processing on the given packet and emits the result.

Processors that defer work asynchronously must either clone the packet or retain an owned equivalent. See [retention()](https://auscaster.com/icey/docs/api-reference/icy-PacketStreamAdapter.md#retention-1).

#### Reimplements

- [`PacketProcessor::process`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#process-1)

---

<a id="accepts-7"></a>

### accepts

`virtual` `inline` `override`

```cpp
virtual inline bool accepts(IPacket *) override
```

[Defined in src/vision/include/icy/vision/framesampler.h:110](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L110)

This method ensures compatibility with the given packet type. Return false to reject the packet.

#### Reimplements

- [`PacketProcessor::accepts`](https://auscaster.com/icey/docs/api-reference/icy-PacketProcessor.md#accepts-1)

## Private Attributes

| Return | Name | Description |
|--------|------|-------------|
| [`FrameSamplerConfig`](https://auscaster.com/icey/docs/api-reference/icy-vision-FrameSamplerConfig.md#framesamplerconfig) | [`_config`](#_config-2)  |  |
| `std::atomic< uint64_t >` | [`_seen`](#_seen-2)  |  |
| `std::atomic< uint64_t >` | [`_forwarded`](#_forwarded)  |  |
| `std::atomic< uint64_t >` | [`_dropped`](#_dropped-2)  |  |
| `std::atomic< int64_t >` | [`_lastForwardedTimeUsec`](#_lastforwardedtimeusec)  |  |

---

<a id="_config-2"></a>

### _config

```cpp
FrameSamplerConfig _config
```

Type: [`FrameSamplerConfig`](https://auscaster.com/icey/docs/api-reference/icy-vision-FrameSamplerConfig.md#framesamplerconfig)

[Defined in src/vision/include/icy/vision/framesampler.h:144](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L144)

---

<a id="_seen-2"></a>

### _seen

```cpp
std::atomic< uint64_t > _seen {0}
```

[Defined in src/vision/include/icy/vision/framesampler.h:145](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L145)

---

<a id="_forwarded"></a>

### _forwarded

```cpp
std::atomic< uint64_t > _forwarded {0}
```

[Defined in src/vision/include/icy/vision/framesampler.h:146](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L146)

---

<a id="_dropped-2"></a>

### _dropped

```cpp
std::atomic< uint64_t > _dropped {0}
```

[Defined in src/vision/include/icy/vision/framesampler.h:147](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L147)

---

<a id="_lastforwardedtimeusec"></a>

### _lastForwardedTimeUsec

```cpp
std::atomic< int64_t > _lastForwardedTimeUsec {kUnsetTimeUsec}
```

[Defined in src/vision/include/icy/vision/framesampler.h:148](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L148)

## Private Methods

| Return | Name | Description |
|--------|------|-------------|
| `bool` | [`shouldForward`](#shouldforward) `const` `inline` |  |

---

<a id="shouldforward"></a>

### shouldForward

`const` `inline`

```cpp
inline bool shouldForward(const av::PlanarVideoPacket & frame, uint64_t seen) const
```

[Defined in src/vision/include/icy/vision/framesampler.h:127](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L127)

## Private Static Attributes

| Return | Name | Description |
|--------|------|-------------|
| `constexpr int64_t` | [`kUnsetTimeUsec`](#kunsettimeusec) `static` `constexpr` |  |

---

<a id="kunsettimeusec"></a>

### kUnsetTimeUsec

`static` `constexpr`

```cpp
constexpr int64_t kUnsetTimeUsec = std::numeric_limits<int64_t>::min()
```

[Defined in src/vision/include/icy/vision/framesampler.h:118](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L118)

## Private Static Methods

| Return | Name | Description |
|--------|------|-------------|
| [`FrameSamplerConfig`](https://auscaster.com/icey/docs/api-reference/icy-vision-FrameSamplerConfig.md#framesamplerconfig) | [`sanitize`](#sanitize-2) `static` `inline` |  |

---

<a id="sanitize-2"></a>

### sanitize

`static` `inline`

```cpp
static inline FrameSamplerConfig sanitize(FrameSamplerConfig config)
```

[Defined in src/vision/include/icy/vision/framesampler.h:120](https://github.com/auscaster/icey/blob/main/src/vision/include/icy/vision/framesampler.h#L120)