FFT and generator C reference
These private instance-operation handlers are not public stubs entries. See FFT workspace and output ownership for dispatch preconditions and commit/callback boundaries.
-
int Rbc_VectorFftOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Transform a real/complex source into existing complex or split-real outputs.
Checks all output types and writability. Copies inputs to owned temporary storage, permitting input/output aliasing. Length must be a nonzero power of two unless explicit padding selects a larger power of two. Forward output is unscaled; inverse input is scaled by 1/N before the butterflies. Installs every output before releasing old storage, flushing caches or notifying clients. Preserves vector identity, type, offset and observers.
Preserves destination records and the interpreter across post-install callbacks. Destroyed destinations are skipped; replacement vectors with the same name are not updated. Returned names are snapshots taken before callbacks.
- Parameters:
vPtr – Live source vector in interp; its full length is transformed.
interp – Owning interpreter, kept alive for the operation.
objc – Argument count already checked by the instance dispatcher.
objv – Instance command arguments, including fft or ifft at index 1.
- Returns:
TCL_OK with a qualified destination name or a two-name list; TCL_ERROR for validation, allocation or non-finite arithmetic errors before commit, with destination data unchanged.
-
int Rbc_VectorFftfreqOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Fill an existing real vector with FFT bin frequencies.
Supports any positive length, not only powers of two. Delta must be finite and positive. Full output uses negative Nyquist for even lengths; one-sided output contains floor(N/2)+1 nonnegative bins. Allocates and validates all values before replacing storage and notifying clients. Does not repeat the dispatcher’s real-type or writable checks. The shared commit helper preserves records across callbacks and skips updates after destruction.
- Parameters:
vPtr – Live, writable real destination, validated by the dispatcher.
interp – Owning interpreter, kept alive for the operation.
objc – Argument count already checked by the instance dispatcher.
objv – Instance command arguments, with positive transform length at index 2.
- Returns:
TCL_OK with the destination name; TCL_ERROR before commit leaves destination data unchanged.
-
int Rbc_VectorWindowOp(VectorObject *vPtr, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Generate unscaled window coefficients in an existing real vector.
Accepts rectangular, Hann, Hamming, Blackman and Bartlett windows of any positive length. Periodic is the default; symmetric uses N-1 instead of N. A length-one window is always one. Stages all coefficients before installing them and notifying clients. Does not repeat the dispatcher’s real-type or writable checks. The shared commit helper preserves records across callbacks and skips updates after destruction.
- Parameters:
vPtr – Live, writable real destination, validated by the dispatcher.
interp – Owning interpreter, kept alive for the operation.
objc – Argument count already checked by the instance dispatcher.
objv – Instance arguments, with window kind and length at indices 2 and 3.
- Returns:
TCL_OK with the destination name; TCL_ERROR before commit leaves destination data unchanged.
Argument ownership and units follow C calling conventions and FFT workspace and output ownership. The operation handlers take full instance command arrays; allocation and kernel helpers take typed value counts. These internal entry points rely on dispatcher or caller preconditions, particularly for writable real generator destinations.
Implementation helpers
- group FFT workspace and commit helpers
Private implementation helpers; not installed C API entry points.
Functions
-
static void *FftAllocate(Tcl_Interp *interp, Tcl_Size count, size_t elementSize)
Allocate checked FFT or generator workspace.
Requires a nonzero elementSize and a positive count. Rejects byte-count overflow before Tcl_AttemptAlloc; reports allocation/size errors in interp. Returns owned storage to release with ckfree, or NULL without changing vectors. No callbacks run.
- Parameters:
interp – [in] Diagnostic interpreter; see Interpreter arguments.
count – [in] Positive number of elements; zero and negative counts are rejected.
elementSize – [in] Nonzero byte width of one element, guaranteed by the caller.
- Returns:
Owned uninitialized Tcl allocation to release with ckfree, or NULL on failure.
-
static void FftTransform(Rbc_Complex *data, const Rbc_Complex *roots, Tcl_Size length)
Transform a power-of-two complex array in place.
The caller supplies a nonempty power-of-two length and length/2 roots exp(sign*2*pi*i*k/length), with negative sign for forward transformation. Roots may be NULL for length one. Inverse normalization belongs to the caller: scale input by 1/length before this kernel. Bit reversal precedes iterative butterflies; output is unshifted. No allocation, validation or callbacks occur. Arithmetic can become non-finite; the caller must validate the complete result.
- Parameters:
data – [inout] Array of length complex values, overwritten by the transform.
roots – [in] Read-only length/2 twiddle factors with the transform’s sign; NULL is allowed for length one.
length – [in] Positive power-of-two count, already validated by the caller.
-
static int FftVector(VectorInterpData *dataPtr, Tcl_Obj *nameObj, VectorObject **vPtrPtr)
Resolve an existing whole-vector operand.
Uses the caller namespace through Rbc_VectorLookupName and rejects a selected range unless it spans the complete vector. Lookup can change the vector’s selected range. On TCL_OK, writes a borrowed record to vPtrPtr; on TCL_ERROR, leaves that output unassigned and sets the interpreter result. Does not create, resize, preserve or test the numeric type/writability of the vector.
- Parameters:
dataPtr – [in] Live owning registry and interpreter used for range-aware lookup.
nameObj – [in] Borrowed vector-reference object, valid throughout lookup.
vPtrPtr – [out] Required borrowed-record output, unchanged on failure; no preservation reference is acquired.
- Returns:
TCL_OK for a complete-vector selection, otherwise TCL_ERROR.
-
static void FftInstall(VectorObject *vPtr, void *data, Tcl_Size length, void **oldDataPtr, Tcl_FreeProc **oldFreeProcPtr)
Install completed storage without crossing a callback boundary.
Requires a writable destination of the correct type and an owned Tcl-allocated buffer with length values. Returns old storage and its release policy through oldDataPtr/oldFreeProcPtr; the caller must release that storage later. Transfers the new buffer to the vector as TCL_DYNAMIC, resets length/capacity/selection, and invalidates extrema. Retains identity, type, offset and observer bindings. Does not flush caches, notify clients, allocate, or release old storage.
- Parameters:
vPtr – [inout] Live writable destination with numeric type matching data.
data – [in] Owned independent Tcl-allocated buffer transferred to vPtr; must not alias its old storage.
length – [in] Nonnegative used count and capacity in typed values.
oldDataPtr – [out] Required output receiving detached old storage; caller releases it according to oldFreeProcPtr.
oldFreeProcPtr – [out] Required output receiving the detached storage’s release policy.
-
static int FftCommit(Tcl_Interp *interp, VectorObject **dest, void **data, int count, Tcl_Size length)
Commit one complex or one/two real output buffers.
count must be one or two; destinations must be distinct, alive, writable and compatible with the supplied buffers. Takes ownership of every buffer and installs all outputs before releasing any old allocation. Preserves destination records and interp across custom free procedures, mapped-array traces and notifications. Skips destroyed records and stops updates after interpreter deletion; it never resolves destination names again after a callback.
Returns TCL_OK with the committed qualified name, or a two-name list, saved before callbacks. Callback mutations are not rolled back; a returned name can have been renamed or destroyed. Restores interpreter state around callbacks. There is no fallible numerical work after installation.
- Parameters:
interp – [in] Owning interpreter shared by the destinations; see Interpreter arguments.
dest – [in] Array of count distinct live writable destinations, validated before entry.
data – [in] Array of count independent completed Tcl allocations, all consumed during installation.
count – [in] Exactly one or two outputs, matching the fixed local bookkeeping arrays.
length – [in] Common used count and capacity in values for every output buffer.
- Returns:
TCL_OK with name snapshots in the interpreter result; callback changes are not rolled back.
-
static int FftStoreReal(VectorObject *vPtr, Tcl_Interp *interp, double *data, Tcl_Size length)
Transfer a completed real generator buffer to its vector.
The caller has checked real type, writability, length and finite values. Consumes the Tcl-allocated data buffer through FftCommit, including old-storage release, cache flushing and notification. Returns TCL_OK with the qualified name recorded at commit time; callbacks can change or destroy the vector.
- Parameters:
vPtr – [inout] Live writable real destination, already validated by the caller.
interp – [in] Owning interpreter; see Interpreter arguments.
data – [in] Completed independent Tcl-allocated real buffer, consumed by the commit.
length – [in] Number of valid finite values in data and resulting destination capacity.
- Returns:
TCL_OK with the destination name captured before commit callbacks.
-
static void *FftAllocate(Tcl_Interp *interp, Tcl_Size count, size_t elementSize)