1 module clFFT; 2 3 import derelict.opencl.cl; 4 5 enum clfftVersionMajor = 2; 6 enum clfftVersionMinor = 1; 7 enum clfftVersionPatch = 0; 8 9 enum clfftStatus 10 { 11 CLFFT_INVALID_GLOBAL_WORK_SIZE = CL_INVALID_GLOBAL_WORK_SIZE, 12 CLFFT_INVALID_MIP_LEVEL = CL_INVALID_MIP_LEVEL, 13 CLFFT_INVALID_BUFFER_SIZE = CL_INVALID_BUFFER_SIZE, 14 CLFFT_INVALID_GL_OBJECT = CL_INVALID_GL_OBJECT, 15 CLFFT_INVALID_OPERATION = CL_INVALID_OPERATION, 16 CLFFT_INVALID_EVENT = CL_INVALID_EVENT, 17 CLFFT_INVALID_EVENT_WAIT_LIST = CL_INVALID_EVENT_WAIT_LIST, 18 CLFFT_INVALID_GLOBAL_OFFSET = CL_INVALID_GLOBAL_OFFSET, 19 CLFFT_INVALID_WORK_ITEM_SIZE = CL_INVALID_WORK_ITEM_SIZE, 20 CLFFT_INVALID_WORK_GROUP_SIZE = CL_INVALID_WORK_GROUP_SIZE, 21 CLFFT_INVALID_WORK_DIMENSION = CL_INVALID_WORK_DIMENSION, 22 CLFFT_INVALID_KERNEL_ARGS = CL_INVALID_KERNEL_ARGS, 23 CLFFT_INVALID_ARG_SIZE = CL_INVALID_ARG_SIZE, 24 CLFFT_INVALID_ARG_VALUE = CL_INVALID_ARG_VALUE, 25 CLFFT_INVALID_ARG_INDEX = CL_INVALID_ARG_INDEX, 26 CLFFT_INVALID_KERNEL = CL_INVALID_KERNEL, 27 CLFFT_INVALID_KERNEL_DEFINITION = CL_INVALID_KERNEL_DEFINITION, 28 CLFFT_INVALID_KERNEL_NAME = CL_INVALID_KERNEL_NAME, 29 CLFFT_INVALID_PROGRAM_EXECUTABLE = CL_INVALID_PROGRAM_EXECUTABLE, 30 CLFFT_INVALID_PROGRAM = CL_INVALID_PROGRAM, 31 CLFFT_INVALID_BUILD_OPTIONS = CL_INVALID_BUILD_OPTIONS, 32 CLFFT_INVALID_BINARY = CL_INVALID_BINARY, 33 CLFFT_INVALID_SAMPLER = CL_INVALID_SAMPLER, 34 CLFFT_INVALID_IMAGE_SIZE = CL_INVALID_IMAGE_SIZE, 35 CLFFT_INVALID_IMAGE_FORMAT_DESCRIPTOR = CL_INVALID_IMAGE_FORMAT_DESCRIPTOR, 36 CLFFT_INVALID_MEM_OBJECT = CL_INVALID_MEM_OBJECT, 37 CLFFT_INVALID_HOST_PTR = CL_INVALID_HOST_PTR, 38 CLFFT_INVALID_COMMAND_QUEUE = CL_INVALID_COMMAND_QUEUE, 39 CLFFT_INVALID_QUEUE_PROPERTIES = CL_INVALID_QUEUE_PROPERTIES, 40 CLFFT_INVALID_CONTEXT = CL_INVALID_CONTEXT, 41 CLFFT_INVALID_DEVICE = CL_INVALID_DEVICE, 42 CLFFT_INVALID_PLATFORM = CL_INVALID_PLATFORM, 43 CLFFT_INVALID_DEVICE_TYPE = CL_INVALID_DEVICE_TYPE, 44 CLFFT_INVALID_VALUE = CL_INVALID_VALUE, 45 CLFFT_MAP_FAILURE = CL_MAP_FAILURE, 46 CLFFT_BUILD_PROGRAM_FAILURE = CL_BUILD_PROGRAM_FAILURE, 47 CLFFT_IMAGE_FORMAT_NOT_SUPPORTED = CL_IMAGE_FORMAT_NOT_SUPPORTED, 48 CLFFT_IMAGE_FORMAT_MISMATCH = CL_IMAGE_FORMAT_MISMATCH, 49 CLFFT_MEM_COPY_OVERLAP = CL_MEM_COPY_OVERLAP, 50 CLFFT_PROFILING_INFO_NOT_AVAILABLE = CL_PROFILING_INFO_NOT_AVAILABLE, 51 CLFFT_OUT_OF_HOST_MEMORY = CL_OUT_OF_HOST_MEMORY, 52 CLFFT_OUT_OF_RESOURCES = CL_OUT_OF_RESOURCES, 53 CLFFT_MEM_OBJECT_ALLOCATION_FAILURE = CL_MEM_OBJECT_ALLOCATION_FAILURE, 54 CLFFT_COMPILER_NOT_AVAILABLE = CL_COMPILER_NOT_AVAILABLE, 55 CLFFT_DEVICE_NOT_AVAILABLE = CL_DEVICE_NOT_AVAILABLE, 56 CLFFT_DEVICE_NOT_FOUND = CL_DEVICE_NOT_FOUND, 57 CLFFT_SUCCESS = CL_SUCCESS, 58 //-------------------------- Extended status codes for clfft 59 //---------------------------------------- 60 CLFFT_BUGCHECK = 4*1024, /*!< Bugcheck. */ 61 CLFFT_NOTIMPLEMENTED, /*!< Functionality is not implemented yet. */ 62 CLFFT_TRANSPOSED_NOTIMPLEMENTED, /*!< Transposed functionality is not implemented for this transformation. */ 63 CLFFT_FILE_NOT_FOUND, /*!< Tried to open an existing file on the host system, but failed. */ 64 CLFFT_FILE_CREATE_FAILURE, /*!< Tried to create a file on the host system, but failed. */ 65 CLFFT_VERSION_MISMATCH, /*!< Version conflict between client and library. */ 66 CLFFT_INVALID_PLAN, /*!< Requested plan could not be found. */ 67 CLFFT_DEVICE_NO_DOUBLE, /*!< Double precision not supported on this device. */ 68 CLFFT_DEVICE_MISMATCH, /*!< Attempt to run on a device using a plan baked for a different device. */ 69 CLFFT_ENDSTATUS /* This value will always be last, and marks the length of clfftStatus. */ 70 } 71 mixin FreeEnumMembers!clfftStatus; 72 73 mixin template FreeEnumMembers(T) 74 if(is(T == enum)) 75 { 76 mixin({ 77 string s; 78 foreach(member; __traits(allMembers, T)) 79 { 80 s ~= "enum T " ~ member ~ " = T." ~ member ~ ",\n"; 81 } 82 return s; 83 }()); 84 } 85 86 /*! @brief The dimension of the input and output buffers that will be fed into all FFT 87 transforms */ 88 enum clfftDim 89 { 90 CLFFT_1D = 1, /*!< 1 Dimensional FFT transform (default). */ 91 CLFFT_2D, /*!< 2 Dimensional FFT transform. */ 92 CLFFT_3D, /*!< 3 Dimensional FFT transform. */ 93 ENDDIMENSION /*!< This value will always be last, and marks the length of clfftDim. */ 94 } 95 mixin FreeEnumMembers!clfftDim; 96 97 /*! @brief These are the expected layouts of the buffers */ 98 enum clfftLayout 99 { 100 CLFFT_COMPLEX_INTERLEAVED = 1, /*!< An array of complex numbers, with real and 101 imaginary components together (default). */ 102 CLFFT_COMPLEX_PLANAR, /*!< Arrays of real componets and arrays of imaginary components that 103 have been seperated out. */ 104 CLFFT_HERMITIAN_INTERLEAVED, /*!< Compressed form of complex numbers; complex-conjugates not 105 stored, real and imaginary components in same array. */ 106 CLFFT_HERMITIAN_PLANAR, /*!< Compressed form of complex numbers; complex-conjugates not stored, 107 real and imaginary components in separate arrays. */ 108 CLFFT_REAL, /*!< An array of real numbers, with no corresponding imaginary components. */ 109 ENDLAYOUT /*!< This value will always be last, and marks the length of clfftLayout. */ 110 } 111 mixin AnonymousEnum!clfftLayout; 112 113 /*! @brief This is the expected precision of each FFT. 114 */ 115 enum clfftPrecision 116 { 117 CLFFT_SINGLE = 1, /*!< An array of complex numbers, with real and imaginary components as 118 floats (default). */ 119 CLFFT_DOUBLE, /*!< An array of complex numbers, with real and imaginary components as 120 doubles. */ 121 CLFFT_SINGLE_FAST, /*!< Faster implementation preferred. */ 122 CLFFT_DOUBLE_FAST, /*!< Faster implementation preferred. */ 123 ENDPRECISION /*!< This value will always be last, and marks the length of clfftPrecision. */ 124 } 125 mixin AnonymousEnum!clfftPrecision; 126 127 /*! @brief What is the expected direction of each FFT, time or the frequency domains */ 128 enum clfftDirection 129 { 130 CLFFT_FORWARD = -1, /*!< FFT transform from the time to the frequency domain. */ 131 CLFFT_BACKWARD = 1, /*!< FFT transform from the frequency to the time domain. */ 132 CLFFT_MINUS = -1, /*!< Alias for the forward transform. */ 133 CLFFT_PLUS = 1, /*!< Alias for the backward transform. */ 134 ENDDIRECTION /*!< This value will always be last, and marks the length of clfftDirection. */ 135 } 136 mixin AnonymousEnum!clfftDirection; 137 138 /*! @brief Are the input buffers overwritten with the results */ 139 enum clfftResultLocation 140 { 141 CLFFT_INPLACE = 1, /*!< The input and output buffers are the same (default). */ 142 CLFFT_OUTOFPLACE, /*!< Seperate input and output buffers. */ 143 ENDPLACE /*!< This value will always be last, and marks the length of clfftPlaceness. */ 144 } 145 mixin AnonymousEnum!clfftResultLocation; 146 147 /*! @brief This determines whether the result is returned in original order. It is valid only 148 for 149 dimensions greater than 1. */ 150 enum clfftResultTransposed { 151 CLFFT_NOTRANSPOSE = 1, /*!< The results are returned in the original preserved order (default) 152 */ 153 CLFFT_TRANSPOSED, /*!< The result is transposed where transpose kernel is supported 154 (possibly faster) */ 155 ENDTRANSPOSED /*!< This value will always be last, and marks the length of 156 clfftResultTransposed */ 157 } 158 mixin AnonymousEnum!clfftResultTransposed; 159 160 /*! BitMasks to be used with clfftSetupData.debugFlags */ 161 enum CLFFT_DUMP_PROGRAMS = 0x1; 162 163 /*! @brief Data structure that can be passed to clfftSetup() to control the behavior of the FFT 164 runtime 165 * @details This structure contains values that can be initialized before instantiation of the 166 FFT runtime 167 * with ::clfftSetup(). To initialize this structure, pass a pointer to a user struct to 168 ::clfftInitSetupData(), 169 * which will clear the structure and set the version member variables to the current values. 170 */ 171 struct clfftSetupData 172 { 173 cl_uint major; /*!< Major version number of the project; signifies major API changes. */ 174 cl_uint minor; /*!< Minor version number of the project; minor API changes that could break 175 backwards compatibility. */ 176 cl_uint patch; /*!< Patch version number of the project; Always incrementing number, signifies 177 change over time. */ 178 179 /*! Bitwise flags that control the behavior of library debug logic. */ 180 cl_ulong debugFlags; /*! This should be set to zero, except when debugging the clfft library. 181 * <p> debugFlags can be set to CLFFT_DUMP_PROGRAMS, in which case the dynamically generated 182 OpenCL kernels will 183 * be written to text files in the current working directory. These files will have a *.cl 184 suffix. 185 */ 186 } 187 188 /*! @brief An abstract handle to the object that represents the state of the FFT(s) */ 189 alias clfftPlanHandle = size_t; 190 191 extern(C): 192 193 /*! @brief Initialize an clfftSetupData struct for the client 194 * @details clfftSetupData is passed to clfftSetup to control behavior of the FFT runtime 195 * @param[out] setupData Data structure is cleared, initialized with version information and 196 default values 197 * @return Enum describing error condition; superset of OpenCL error codes 198 */ 199 clfftStatus clfftInitSetupData(clfftSetupData* setupData) 200 { 201 setupData.major = clfftVersionMajor; 202 setupData.minor = clfftVersionMinor; 203 setupData.patch = clfftVersionPatch; 204 setupData.debugFlags = 0; 205 206 return CLFFT_SUCCESS; 207 } 208 209 /*! @brief Initialize internal FFT resources. 210 * @details AMD's FFT implementation caches kernels, programs and buffers for its internal use. 211 * @param[in] setupData Data structure that can be passed into the setup routine to control FFT 212 generation behavior 213 * and debug functionality 214 * @return Enum describing error condition; superset of OpenCL error codes 215 */ 216 clfftStatus clfftSetup(const clfftSetupData* setupData); 217 218 /*! @brief Release all internal resources. 219 * @details Call when client is done with this FFT library, allowing the library to destroy all 220 resources it has cached 221 * @return Enum describing error condition; superset of OpenCL error codes 222 */ 223 clfftStatus clfftTeardown(); 224 225 /*! @brief Query the FFT library for version information 226 * @details Return the major, minor and patch version numbers associated with this FFT library 227 * @param[out] major Major functionality change 228 * @param[out] minor Minor functionality change 229 * @param[out] patch Bug fixes, documentation changes, no new features introduced 230 * @return Enum describing error condition; superset of OpenCL error codes 231 */ 232 clfftStatus clfftGetVersion(cl_uint* major, cl_uint* minor, cl_uint* patch); 233 234 /*! @brief Create a plan object initialized entirely with default values. 235 * @details A plan is a repository of state for calculating FFT's. Allows the runtime to 236 pre-calculate kernels, programs 237 * and buffers and associate them with buffers of specified dimensions. 238 * @param[out] plHandle Handle to the newly created plan 239 * @param[in] context Client is responsible for providing an OpenCL context for the plan 240 * @param[in] dim The dimensionality of the FFT transform; describes how many elements are in 241 the array 242 * @param[in] clLengths An array of lengths, of size 'dim'. Each value describes the length of 243 additional dimensions 244 * @return Enum describing error condition; superset of OpenCL error codes 245 */ 246 clfftStatus clfftCreateDefaultPlan(clfftPlanHandle* plHandle, cl_context context, 247 const clfftDim dim, 248 const size_t* clLengths); 249 250 /*! @brief Create a copy of an existing plan. 251 * @details This API allows a client to create a new plan based upon an existing plan. This is a 252 convenience function 253 * provided for quickly creating plans that are similar, but may differ slightly. 254 * @param[out] out_plHandle Handle to the newly created plan that is based on in_plHandle 255 * @param[in] new_context Client is responsible for providing a new context for the new plan 256 * @param[in] in_plHandle Handle to a plan to be copied, previously created 257 * @return Enum describing error condition; superset of OpenCL error codes 258 */ 259 clfftStatus clfftCopyPlan(clfftPlanHandle* out_plHandle, cl_context new_context, 260 clfftPlanHandle in_plHandle); 261 262 /*! @brief Prepare the plan for execution. 263 * @details After all plan parameters are set, the client has the option of 'baking' the plan, 264 which tells the runtime that 265 * no more changes to the plan's parameters are expected, and the OpenCL kernels should be 266 compiled. This optional function 267 * allows the client application to perform this function when the application is being 268 initialized instead of on the first 269 * execution. 270 * At this point, the clfft runtime will apply all implimented optimizations, possibly including 271 * running kernel experiments on the devices in the plan context. 272 * <p> Users should assume that this function will take a long time to execute. If a plan is not 273 baked before being executed, 274 * users should assume that the first call to clfftEnqueueTransform will take a long time to 275 execute. 276 * <p> If any significant parameter of a plan is changed after the plan is baked (by a 277 subsequent call to one of 278 * the clfftSetPlan____ functions), that will not be considered an error. Instead, the plan will 279 revert back to 280 * the unbaked state, discarding the benefits of the baking operation. 281 * @param[in] plHandle Handle to a plan previously created 282 * @param[in] numQueues Number of command queues in commQueueFFT; 0 is a valid value, in which 283 case client does not want 284 * the runtime to run load experiments and only pre-calculate state information 285 * @param[in] commQueueFFT An array of cl_command_queues created by the client; the command 286 queues must be a proper subset of 287 * the devices included in the plan context 288 * @param[in] pfn_notify A function pointer to a notification routine. The notification routine 289 is a callback function that 290 * an application can register and which will be called when the program executable has been 291 built (successfully or unsuccessfully). 292 * Currently, this parameter MUST be NULL or nullptr. 293 * @param[in] user_data Passed as an argument when pfn_notify is called. 294 * Currently, this parameter MUST be NULL or nullptr. 295 * @return Enum describing error condition; superset of OpenCL error codes 296 */ 297 clfftStatus clfftBakePlan(clfftPlanHandle plHandle, cl_uint numQueues, 298 cl_command_queue* commQueueFFT, 299 void function(clfftPlanHandle plHandle, void* user_data) pfn_notify, void* user_data); 300 301 /*! @brief Release the resources of a plan. 302 * @details A plan may include kernels, programs and buffers associated with it that consume 303 memory. When a plan 304 * is not needed anymore, the client should release the plan. 305 * @param[in,out] plHandle Handle to a plan previously created 306 * @return Enum describing error condition; superset of OpenCL error codes 307 */ 308 clfftStatus clfftDestroyPlan(clfftPlanHandle* plHandle); 309 310 /*! @brief Retrieve the OpenCL context of a previously created plan. 311 * @details User should pass a reference to an cl_context variable, which will be changed to 312 point to a 313 * context set in the specified plan. 314 * @param[in] plHandle Handle to a plan previously created 315 * @param[out] context Reference to user allocated cl_context, which will point to context set 316 in plan 317 * @return Enum describing error condition; superset of OpenCL error codes 318 */ 319 clfftStatus clfftGetPlanContext(const clfftPlanHandle plHandle, cl_context* 320 context); 321 322 /*! @brief Retrieve the floating point precision of the FFT data 323 * @details User should pass a reference to an clfftPrecision variable, which will be set to the 324 * precision of the FFT complex data in the plan. 325 * @param[in] plHandle Handle to a plan previously created 326 * @param[out] precision Reference to user clfftPrecision enum 327 * @return Enum describing error condition; superset of OpenCL error codes 328 */ 329 clfftStatus clfftGetPlanPrecision(const clfftPlanHandle plHandle, clfftPrecision* 330 precision); 331 332 /*! @brief Set the floating point precision of the FFT data 333 * @details Set the plan property which will be the precision of the FFT complex data in the 334 plan. 335 * @param[in] plHandle Handle to a plan previously created 336 * @param[in] precision Reference to user clfftPrecision enum 337 * @return Enum describing error condition; superset of OpenCL error codes 338 */ 339 clfftStatus clfftSetPlanPrecision(clfftPlanHandle plHandle, clfftPrecision 340 precision); 341 342 /*! @brief Retrieve the scaling factor that should be applied to the FFT data 343 * @details User should pass a reference to an cl_float variable, which will be set to the 344 * floating point scaling factor that will be multiplied across the FFT data. 345 * @param[in] plHandle Handle to a plan previously created 346 * @param[in] dir Which direction does the scaling factor apply to 347 * @param[out] scale Reference to user cl_float variable 348 * @return Enum describing error condition; superset of OpenCL error codes 349 */ 350 clfftStatus clfftGetPlanScale(const clfftPlanHandle plHandle, clfftDirection dir, 351 cl_float* scale); 352 353 /*! @brief Set the scaling factor that should be applied to the FFT data 354 * @details Set the plan property which will be the floating point scaling factor that will be 355 * multiplied across the FFT data. 356 * @param[in] plHandle Handle to a plan previously created 357 * @param[in] dir Which direction does the scaling factor apply to 358 * @param[in] scale Reference to user cl_float variable 359 * @return Enum describing error condition; superset of OpenCL error codes 360 */ 361 clfftStatus clfftSetPlanScale(clfftPlanHandle plHandle, clfftDirection dir, 362 cl_float scale); 363 364 /*! @brief Retrieve the number of discrete arrays that this plan can handle concurrently 365 * @details User should pass a reference to an cl_uint variable, which will be set to the 366 * number of discrete arrays (1D or 2D) that will be batched together for this plan 367 * @param[in] plHandle Handle to a plan previously created 368 * @param[out] batchSize How many discrete number of FFT's are to be performed 369 * @return Enum describing error condition; superset of OpenCL error codes 370 */ 371 clfftStatus clfftGetPlanBatchSize(const clfftPlanHandle plHandle, size_t* 372 batchSize); 373 374 /*! @brief Set the number of discrete arrays that this plan can handle concurrently 375 * @details Set the plan property which will be set to the number of discrete arrays (1D or 2D) 376 * that will be batched together for this plan 377 * @param[in] plHandle Handle to a plan previously created 378 * @param[in] batchSize How many discrete number of FFT's are to be performed 379 * @return Enum describing error condition; superset of OpenCL error codes 380 */ 381 clfftStatus clfftSetPlanBatchSize(clfftPlanHandle plHandle, size_t batchSize); 382 383 /*! @brief Retrieve the dimensionality of FFT's to be transformed in the plan 384 * @details Queries a plan object and retrieves the dimensionality that the plan is set for. A 385 size is returned to 386 * help the client allocate the proper storage to hold the dimensions in a further call to 387 clfftGetPlanLength 388 * @param[in] plHandle Handle to a plan previously created 389 * @param[out] dim The dimensionality of the FFT's to be transformed 390 * @param[out] size Value used to allocate an array to hold the FFT dimensions. 391 * @return Enum describing error condition; superset of OpenCL error codes 392 */ 393 clfftStatus clfftGetPlanDim(const clfftPlanHandle plHandle, clfftDim* dim, 394 cl_uint* size); 395 396 /*! @brief Set the dimensionality of FFT's to be transformed by the plan 397 * @details Set the dimensionality of FFT's to be transformed by the plan 398 * @param[in] plHandle Handle to a plan previously created 399 * @param[in] dim The dimensionality of the FFT's to be transformed 400 * @return Enum describing error condition; superset of OpenCL error codes 401 */ 402 clfftStatus clfftSetPlanDim(clfftPlanHandle plHandle, const clfftDim dim); 403 404 /*! @brief Retrieve the length of each dimension of the FFT 405 * @details User should pass a reference to a size_t array, which will be set to the 406 * length of each discrete dimension of the FFT 407 * @param[in] plHandle Handle to a plan previously created 408 * @param[in] dim The dimension of the length parameters; describes how many elements are in the 409 array 410 * @param[out] clLengths An array of lengths, of size 'dim'. Each array value describes the 411 length of each dimension 412 * @return Enum describing error condition; superset of OpenCL error codes 413 */ 414 clfftStatus clfftGetPlanLength(const clfftPlanHandle plHandle, const clfftDim dim, 415 size_t* clLengths); 416 417 /*! @brief Set the length of each dimension of the FFT 418 * @details Set the plan property which will be the length of each discrete dimension of the FFT 419 * @param[in] plHandle Handle to a plan previously created 420 * @param[in] dim The dimension of the length parameters; describes how many elements are in the 421 array 422 * @param[in] clLengths An array of lengths, of size 'dim'. Each value describes the length of 423 additional dimensions 424 * @return Enum describing error condition; superset of OpenCL error codes 425 */ 426 clfftStatus clfftSetPlanLength(clfftPlanHandle plHandle, const clfftDim dim, const 427 size_t* clLengths); 428 429 /*! @brief Retrieve the distance between consecutive elements for input buffers in a dimension. 430 * @details Depending on how the dimension is set in the plan (for 2D or 3D FFT's), strideY or 431 strideZ can be safely 432 * ignored 433 * @param[in] plHandle Handle to a plan previously created 434 * @param[in] dim The dimension of the stride parameters; describes how many elements are in the 435 array 436 * @param[out] clStrides An array of strides, of size 'dim'. 437 */ 438 clfftStatus clfftGetPlanInStride(const clfftPlanHandle plHandle, const clfftDim 439 dim, size_t* clStrides); 440 441 /*! @brief Set the distance between consecutive elements for input buffers in a dimension. 442 * @details Set the plan properties which will be the distance between elements in a given 443 dimension 444 * (units are in terms of clfftPrecision) 445 * @param[in] plHandle Handle to a plan previously created 446 * @param[in] dim The dimension of the stride parameters; describes how many elements are in the 447 array 448 * @param[in] clStrides An array of strides, of size 'dim'. Usually strideX=1 so that successive 449 elements in the first dimension are stored contiguously. 450 * Typically strideY=LenX, strideZ=LenX*LenY such that successive elements in the second and 451 third dimensions are stored in packed format. 452 * See @ref DistanceStridesandPitches for details. 453 */ 454 clfftStatus clfftSetPlanInStride(clfftPlanHandle plHandle, const clfftDim dim, 455 size_t* clStrides); 456 457 /*! @brief Retrieve the distance between consecutive elements for output buffers in a 458 dimension. 459 * @details Depending on how the dimension is set in the plan (for 2D or 3D FFT's), strideY or 460 strideZ can be safely 461 * ignored 462 * @param[in] plHandle Handle to a plan previously created 463 * @param[in] dim The dimension of the stride parameters; describes how many elements are in the 464 array 465 * @param[out] clStrides An array of strides, of size 'dim'. 466 */ 467 clfftStatus clfftGetPlanOutStride(const clfftPlanHandle plHandle, const clfftDim 468 dim, size_t* clStrides); 469 470 /*! @brief Set the distance between consecutive elements for output buffers in a dimension. 471 * @details Set the plan properties which will be the distance between elements in a given 472 dimension 473 * (units are in terms of clfftPrecision) 474 * @param[in] plHandle Handle to a plan previously created 475 * @param[in] dim The dimension of the stride parameters; describes how many elements are in the 476 array 477 * @param[in] clStrides An array of strides, of size 'dim'. Usually strideX=1 so that successive 478 elements in the first dimension are stored contiguously. 479 * Typically strideY=LenX, strideZ=LenX*LenY such that successive elements in the second and 480 third dimensions are stored in packed format. 481 * @sa clfftSetPlanInStride 482 */ 483 clfftStatus clfftSetPlanOutStride(clfftPlanHandle plHandle, const clfftDim dim, 484 size_t* clStrides); 485 486 /*! @brief Retrieve the distance between Array objects 487 * @details Pitch is the distance between each discrete array object in an FFT array. This is 488 only used 489 * for 'array' dimensions in clfftDim; see clfftSetPlanDimension (units are in terms of 490 clfftPrecision) 491 * @param[in] plHandle Handle to a plan previously created 492 * @param[out] iDist The distance between the beginning elements of the discrete array objects 493 in memory on input. 494 * For contiguous arrays in memory, iDist=(strideX*strideY*strideZ) 495 * @param[out] oDist The distance between the beginning elements of the discrete array objects 496 in memory on output. 497 * For contiguous arrays in memory, oDist=(strideX*strideY*strideZ) 498 */ 499 clfftStatus clfftGetPlanDistance(const clfftPlanHandle plHandle, size_t* iDist, 500 size_t* oDist); 501 502 /*! @brief Set the distance between Array objects 503 * @details Pitch is the distance between each discrete array object in an FFT array. This is 504 only used 505 * for 'array' dimensions in clfftDim; see clfftSetPlanDimension (units are in terms of 506 clfftPrecision) 507 * @param[in] plHandle Handle to a plan previously created 508 * @param[out] iDist The distance between the beginning elements of the discrete array objects 509 in memory on input. 510 * For contiguous arrays in memory, iDist=(strideX*strideY*strideZ) 511 * @param[out] oDist The distance between the beginning elements of the discrete array objects 512 in memory on output. 513 * For contiguous arrays in memory, oDist=(strideX*strideY*strideZ) 514 */ 515 clfftStatus clfftSetPlanDistance(clfftPlanHandle plHandle, size_t iDist, size_t 516 oDist); 517 518 /*! @brief Retrieve the expected layout of the input and output buffers 519 * @details Output buffers can be filled with either hermitian or complex numbers. Complex 520 numbers can be stored 521 * in various layouts; this informs the FFT engine what layout to produce on output 522 * @param[in] plHandle Handle to a plan previously created 523 * @param[out] iLayout Indicates how the input buffers are laid out in memory 524 * @param[out] oLayout Indicates how the output buffers are laid out in memory 525 */ 526 clfftStatus clfftGetLayout(const clfftPlanHandle plHandle, clfftLayout* iLayout, 527 clfftLayout* oLayout); 528 529 /*! @brief Set the expected layout of the input and output buffers 530 * @details Output buffers can be filled with either hermitian or complex numbers. Complex 531 numbers can be stored 532 * in various layouts; this informs the FFT engine what layout to produce on output 533 * @param[in] plHandle Handle to a plan previously created 534 * @param[in] iLayout Indicates how the input buffers are laid out in memory 535 * @param[in] oLayout Indicates how the output buffers are laid out in memory 536 */ 537 clfftStatus clfftSetLayout(clfftPlanHandle plHandle, clfftLayout iLayout, 538 clfftLayout oLayout); 539 540 /*! @brief Retrieve whether the input buffers are going to be overwritten with results 541 * @details If the setting is to do an in-place transform, the input buffers are overwritten 542 with the results of the 543 * transform. If the setting is for out-of-place transforms, the engine knows to look for 544 separate output buffers 545 * on the Enqueue call. 546 * @param[in] plHandle Handle to a plan previously created 547 * @param[out] placeness Tells the FFT engine to clobber the input buffers or to expect output 548 buffers for results 549 */ 550 clfftStatus clfftGetResultLocation(const clfftPlanHandle plHandle, 551 clfftResultLocation* placeness); 552 553 /*! @brief Set whether the input buffers are going to be overwritten with results 554 * @details If the setting is to do an in-place transform, the input buffers are overwritten 555 with the results of the 556 * transform. If the setting is for out-of-place transforms, the engine knows to look for 557 separate output buffers 558 * on the Enqueue call. 559 * @param[in] plHandle Handle to a plan previously created 560 * @param[in] placeness Tells the FFT engine to clobber the input buffers or to expect output 561 buffers for results 562 */ 563 clfftStatus clfftSetResultLocation(clfftPlanHandle plHandle, clfftResultLocation 564 placeness); 565 566 /*! @brief Retrieve the final transpose setting of a muti-dimensional FFT 567 * @details A multi-dimensional FFT typically transposes the data several times during 568 calculation. If the client 569 * does not care about the final transpose to put data back in proper dimension, the final 570 transpose can be skipped 571 * for possible speed improvements 572 * @param[in] plHandle Handle to a plan previously created 573 * @param[out] transposed Parameter specifies whether the final transpose can be skipped 574 */ 575 clfftStatus clfftGetPlanTransposeResult(const clfftPlanHandle plHandle, 576 clfftResultTransposed* transposed); 577 578 /*! @brief Set the final transpose setting of a muti-dimensional FFT 579 * @details A multi-dimensional FFT typically transposes the data several times during 580 calculation. If the client 581 * does not care about the final transpose to put data back in proper dimension, the final 582 transpose can be skipped 583 * for possible speed improvements 584 * @param[in] plHandle Handle to a plan previously created 585 * @param[in] transposed Parameter specifies whether the final transpose can be skipped 586 */ 587 clfftStatus clfftSetPlanTransposeResult(clfftPlanHandle plHandle, 588 clfftResultTransposed transposed); 589 590 591 /*! @brief Get buffer size (in bytes), which may be needed internally for an intermediate 592 buffer 593 * @details Very large FFT transforms may need multiple passes, and the operation would need a 594 temporary buffer to hold 595 * intermediate results. This function is only valid after the plan is baked, otherwise an 596 invalid operation error 597 * is returned. If buffersize returns as 0, the runtime needs no temporary buffer. 598 * @param[in] plHandle Handle to a plan previously created 599 * @param[out] buffersize Size in bytes for intermediate buffer 600 */ 601 clfftStatus clfftGetTmpBufSize(const clfftPlanHandle plHandle, size_t* buffersize); 602 603 /*! @brief Enqueue an FFT transform operation, and return immediately (non-blocking) 604 * @details This transform API is the function that actually computes the FFT transfrom. It is 605 non-blocking as it 606 * only enqueues the OpenCL kernels for execution. The synchronization step has to be managed by 607 the user. 608 * @param[in] plHandle Handle to a plan previously created 609 * @param[in] dir Forwards or backwards transform 610 * @param[in] numQueuesAndEvents Number of command queues in commQueues; number of expected 611 events to be returned in outEvents 612 * @param[in] commQueues An array of cl_command_queues created by the client; the command queues 613 must be a proper subset of 614 * the devices included in the plan context 615 * @param[in] numWaitEvents Specify the number of elements in the eventWaitList array 616 * @param[in] waitEvents Events that this transform should wait to complete before executing on 617 the device 618 * @param[out] outEvents The runtime fills this array with events corresponding 1 to 1 with the 619 input command queues passed 620 * in commQueues. This parameter can be NULL or nullptr, in which case client is not interested 621 in receiving notifications 622 * when transforms are finished, otherwise if not NULL the client is responsible for allocating 623 this array, with at least 624 * as many elements as specified in numQueuesAndEvents. 625 * @param[in] inputBuffers An array of cl_mem objects that contain data for processing by the 626 FFT runtime. If the transform 627 * is in place, the FFT results will overwrite the input buffers 628 * @param[out] outputBuffers An array of cl_mem objects that will store the results of out of 629 place transforms. If the transform 630 * is in place, this parameter may be NULL or nullptr. It is completely ignored 631 * @param[in] tmpBuffer A cl_mem object that is reserved as a temporary buffer for FFT 632 processing. If clTmpBuffers is NULL or nullptr, 633 * and the runtime needs temporary storage, an internal temporary buffer will be created on the 634 fly managed by the runtime. 635 * @return Enum describing error condition; superset of OpenCL error codes 636 */ 637 clfftStatus clfftEnqueueTransform( 638 clfftPlanHandle plHandle, 639 clfftDirection dir, 640 cl_uint numQueuesAndEvents, 641 cl_command_queue* commQueues, 642 cl_uint numWaitEvents, 643 const cl_event* waitEvents, 644 cl_event* outEvents, 645 cl_mem* inputBuffers, 646 cl_mem* outputBuffers, 647 cl_mem tmpBuffer 648 ); 649