DftiCreateDescriptor

Developer Reference for Intel® oneAPI Math Kernel Library for C

Download PDF

ID 766684

Date 11/07/2023

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-2E31EB2D-15B4-481B-B40F-FE7B6CDDCEDF

View Details

DftiCreateDescriptor

Allocates the descriptor data structure and initializes it with default configuration values.

Syntax

status = DftiCreateDescriptor(&desc_handle, precision, forward_domain, dimension, length);

Include Files

mkl.h

Input Parameters

Name	Type	Description
precision	enum	Precision of the transform: `DFTI_SINGLE` or `DFTI_DOUBLE`.
forward_domain	enum	Forward domain of the transform: `DFTI_COMPLEX` or `DFTI_REAL`.
dimension	MKL_LONG	Dimension of the transform.
length	MKL_LONG if dimension = 1. Array of type MKL_LONG otherwise.	Length of the transform for a one-dimensional transform. Lengths of each dimension for a multi-dimensional transform.

Output Parameters

Name	Type	Description
desc_handle	DFTI_DESCRIPTOR_HANDLE	FFT descriptor.
status	MKL_LONG	Function completion status.

Description

This function allocates memory for the descriptor data structure and instantiates it with all the default configuration settings for the precision, forward domain, dimension, and length of the desired transform. Because memory is allocated dynamically, the result is actually a pointer to the created descriptor. This function is slightly different from the "initialization" function that can be found in software packages or libraries that implement more traditional algorithms for computing an FFT. This function does not perform any significant computational work such as computation of twiddle factors. The function DftiCommitDescriptor does this work after the function DftiSetValue has set values of all necessary parameters.

The function returns zero when it completes successfully. See Status Checking Functions for more information on the returned status.

Prototype

 
/* Note that the preprocessor definition provided below only illustrates 
 * that the actual function called may be determined at compile time. 
 * You can rely only on the declaration of the function. 
 * For precise definition of the preprocessor macro, see the include/mkl_dfti.h
 * file in the Intel MKL directory.
 */
MKL_LONG DftiCreateDescriptor(DFTI_DESCRIPTOR_HANDLE * pHandle,
     enum DFTI_CONFIG_VALUE precision,
     enum DFTI_CONFIG_VALUE domain,
     MKL_LONG dimension, ... /* length/lengths */ );
				 
#define DftiCreateDescriptor(desc,prec,domain,dim,sizes) \
     ((prec)==DFTI_SINGLE && (dim)==1) ? \
     some_actual_function_s1d((desc),(domain),(MKL_LONG)(sizes)) : \
     ...

Variable length/lengths is interpreted as a scalar (MKL_LONG) or an array (MKL_LONG*), depending on the value of parameter dimension. If the value of parameter precision is known at compile time, an optimizing compiler retains only the call to the respective specific function, thereby reducing the size of the statically linked application. Avoid direct calls to the specific functions used in the preprocessor macro definition, because their interface may change in future releases of the library. If the use of the macro is undesirable, you can safely undefine it after inclusion of the Intel® oneAPI Math Kernel Library (oneMKL) FFT header file, as follows:

#include "mkl_dfti.h"
#undef DftiCreateDescriptor

Parent topic: FFT Descriptor Manipulation Functions

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

Developer Reference for Intel® oneAPI Math Kernel Library for C

DftiCreateDescriptor

Syntax

Include Files

Input Parameters

Output Parameters

Description

Prototype

See Also