File delay_core.h¶

FileList > delay > delay_core.h

Go to the source code of this file

Delay component API. More...

• #include "doppler/clib_common.h"
• #include "doppler/jm_perf.h"
• #include "doppler/dp_state.h"

Classes¶

Public Functions¶

Macros¶

Detailed Description¶

Lifecycle: create -> (step / steps / reset)* -> destroy

Example:

dp_delay_state_t *obj = dp_delay_create();
float _Complex y = delay_step(obj, 0.0f + 0.0f * I);
dp_delay_destroy(obj);

Public Functions Documentation¶

function dp_delay_create¶

Create a dual-buffer circular delay line of length num_taps. The internal capacity is rounded up to the next power of two so that modular indexing reduces to a single bitwise AND. Any window of num_taps consecutive samples is always contiguous in the backing store; no wrap-around copy is ever needed.

dp_delay_state_t * dp_delay_create (
    size_t num_taps
) 

Parameters:

• num_taps Number of delay taps (window length, >= 1). Internally rounded up to the next power of two.

Returns:

Heap-allocated state, or NULL on allocation failure.

>>> from doppler.delay import DelayCf64
>>> d = DelayCf64(num_taps=3)
>>> d.num_taps
3
>>> d.capacity   # next power-of-two >= 3
4

function dp_delay_destroy¶

Destroy a delay instance and release all memory. Frees the internal dual buffer and the state struct itself. Safe to call with a NULL pointer (no-op). After this call the pointer must not be used; the Python binding raises RuntimeError on any subsequent method call.

void dp_delay_destroy (
    dp_delay_state_t * state
) 

Parameters:

• state Heap-allocated delay state, or NULL.

  >>> from doppler.delay import DelayCf64
  >>> d = DelayCf64(num_taps=2)
  >>> d.push(1+0j)
  >>> d.destroy()
  >>> try:
  ...     d.push(2+0j)
  ... except RuntimeError as e:
  ...     print(e)
  destroyed
  

function dp_delay_get_state¶

void dp_delay_get_state (
    const dp_delay_state_t * state,
    void * blob
) 

function dp_delay_ptr¶

Snapshot the n most recent samples. Copies at most min(n, num_taps) samples starting from buf[head] into out. Because the dual-buffer layout guarantees contiguity, this is a single memcpy of up to num_taps elements; no wrap-around logic is needed. The Python binding returns an independent NumPy array per call, so an earlier snapshot is never overwritten by a later one; passout= to fill a caller-owned buffer instead of allocating.

size_t dp_delay_ptr (
    dp_delay_state_t * state,
    size_t n,
    double _Complex * out,
    size_t max_out
) 

Parameters:

• state Must be non-NULL.
• n Number of samples to copy; clamped to num_taps.
• out Output buffer; must hold at least max_out elements.
• max_out Capacity of out in samples. Normally num_taps (what dp_delay_ptr_max_out() reports); a smaller value truncates the snapshot instead of overrunning the buffer.

Returns:

min(n, num_taps, max_out) samples.

>>> from doppler.delay import DelayCf64
>>> d = DelayCf64(num_taps=3)
>>> d.push(1+0j)
>>> d.push(2+0j)
>>> y = d.ptr()
>>> y.tolist()
[(2+0j), (1+0j), 0j]
>>> y.dtype
dtype('complex128')
>>> y.shape
(3,)

function dp_delay_ptr_max_out¶

Maximum samples dp_delay_ptr() writes for a request of n. Returns min(n, num_taps) — the tight per-call bound (gh-607).

size_t dp_delay_ptr_max_out (
    dp_delay_state_t * state,
    size_t n
) 

Parameters:

• state Must be non-NULL.
• n Number of samples the matching dp_delay_ptr() call requests.

Returns:

min(n, num_taps).

function dp_delay_push¶

Advance the write pointer and insert a new sample. The head pointer decrements (mod capacity) before the write so that buf[head] always holds the most recent sample. The same value is simultaneously written atbuf[head + capacity] to keep the mirror half in sync; this ensures any num_taps-length window starting at head is contiguous without an extra copy.

void dp_delay_push (
    dp_delay_state_t * state,
    double _Complex x
) 

Parameters:

• state Must be non-NULL.
• x New complex sample to insert.

  >>> from doppler.delay import DelayCf64
  >>> d = DelayCf64(num_taps=3)
  >>> d.push(1+2j)
  >>> d.push(3+4j)
  >>> d.ptr().tolist()
  [(3+4j), (1+2j), 0j]
  

function dp_delay_push_ptr¶

Atomically push a sample and snapshot the current window. Equivalent to calling dp_delay_push() then dp_delay_ptr(num_taps), but avoids the overhead of a second function call. Always writes exactly num_taps samples to out. The Python binding returns an independent NumPy array per call; passout= to reuse one buffer across pushes.

size_t dp_delay_push_ptr (
    dp_delay_state_t * state,
    double _Complex x,
    double _Complex * out,
    size_t max_out
) 

Parameters:

• state Must be non-NULL.
• x New complex sample to insert.
• out Output buffer; must hold at least max_out elements.
• max_out Capacity of out in samples. Normally num_taps. The push happens either way the ring is a running window and cannot be left un-advanced but a smaller capacity truncates the snapshot that is handed back.

Returns:

min(num_taps, max_out) samples.

>>> from doppler.delay import DelayCf64
>>> d = DelayCf64(num_taps=3)
>>> d.push_ptr(1+0j).tolist()
[(1+0j), 0j, 0j]
>>> d.push_ptr(2+0j).tolist()
[(2+0j), (1+0j), 0j]

function dp_delay_push_ptr_max_out¶

Return the maximum output capacity for dp_delay_push_ptr() . Returns num_taps; the Python binding sizes each call's output array with it, and checks a caller'sout= buffer against it.

size_t dp_delay_push_ptr_max_out (
    dp_delay_state_t * state
) 

Parameters:

• state Must be non-NULL.

Returns:

num_taps (number of samples dp_delay_push_ptr() will write).

function dp_delay_reset¶

Reset the delay line to its post-create state. Zeroes the entire dual buffer and resets the write pointer to 0, discarding all previously pushed samples. The num_taps and capacity are preserved; only the sample history is cleared.

void dp_delay_reset (
    dp_delay_state_t * state
) 

Parameters:

• state Must be non-NULL.

  >>> from doppler.delay import DelayCf64
  >>> d = DelayCf64(num_taps=3)
  >>> d.push(1+2j)
  >>> d.push(3+4j)
  >>> d.ptr().tolist()
  [(3+4j), (1+2j), 0j]
  >>> d.reset()
  >>> d.ptr().tolist()
  [0j, 0j, 0j]
  

function dp_delay_set_state¶

int dp_delay_set_state (
    dp_delay_state_t * state,
    const void * blob
) 

function dp_delay_state_bytes¶

size_t dp_delay_state_bytes (
    const dp_delay_state_t * state
) 

function dp_delay_write¶

Alias for dp_delay_push() ; insert a sample without reading back. Provided for API symmetry with write-then-read patterns where the caller wants to decouple sample ingestion from window inspection. Internally delegates todp_delay_push() with no additional overhead.

void dp_delay_write (
    dp_delay_state_t * state,
    double _Complex x
) 

Parameters:

• state Must be non-NULL.
• x New complex sample to insert.

  >>> from doppler.delay import DelayCf64
  >>> d = DelayCf64(num_taps=2)
  >>> d.write(5+6j)
  >>> d.ptr().tolist()
  [(5+6j), 0j]
  

Macro Definition Documentation¶

define DELAY_STATE_MAGIC¶

#define DELAY_STATE_MAGIC `DP_FOURCC ('D','L','A','Y')`

define DELAY_STATE_VERSION¶

#define DELAY_STATE_VERSION `1u`

The documentation for this class was generated from the following file native/inc/doppler/delay/delay_core.h