Developer Reference for Intel® oneAPI Math Kernel Library for C

ID 766684
Date 3/22/2024
Public

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

Document Table of Contents

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
			

See Also