# pffft

**Repository Path**: matace/pffft

## Basic Information

- **Project Name**: pffft
- **Description**: 快速FFT计算
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-05
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PFFFT - FFT API 封装库

高性能 FFT (快速傅里叶变换) C 语言库，基于 PFFFT 实现，提供完整易用的 API 接口。

## ✨ 特性

- 🚀 **高性能**：利用 SIMD 指令集优化（SSE、NEON、Altivec）
- 📦 **易用接口**：简洁的 C 语言 API，符合 Doxygen 规范
- 🔧 **功能完整**：
  - 复数 FFT（正向/逆向）
  - 实数 FFT（正向/逆向）
  - 频谱分析（幅度谱、功率谱、对数幅度谱）
  - 频域卷积
- 💻 **跨平台**：支持 Linux、Windows、macOS
- 🎯 **高精度**：32 位单精度浮点运算
- 📐 **灵活大小**：支持 N=(2^a)×(3^b)×(5^c) 的 FFT 大小

## 📁 项目结构

```
pffft/
├── CMakeLists.txt          # CMake 构建配置
├── README.md               # 本文件
├── FFT_API_GUIDE.md        # 详细使用指南
├── include/
│   ├── pffft.h            # PFFFT 原始头文件
│   └── fft_api.h          # FFT API 封装头文件
├── src/
│   ├── pffft.c            # PFFFT 原始实现
│   └── fft_api.c          # FFT API 封装实现
├── test/
│   └── fft_test.c         # 测试程序
└── nativedsp.cpp          # Android JNI 参考实现
```

## 🚀 快速开始

### 编译

```bash
# 创建构建目录
mkdir build && cd build

# 配置（Release 模式）
cmake -DCMAKE_BUILD_TYPE=Release ..

# 编译
make -j$(nproc)

# 安装（可选）
sudo make install
```

### 编译测试程序

```bash
# 启用测试
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON ..
make

# 运行测试
./fft_test
```

## 📝 基本用法

### 复数 FFT 示例

```c
#include "fft_api.h"

int main() {
    // 1. 创建 FFT 上下文（512 点复数 FFT）
    FFT_Context* ctx = fft_create_context(512, FFT_TRANSFORM_COMPLEX);
    
    // 2. 准备输入数据（1024 个浮点数：512 个复数）
    float input[1024];   // 格式：[real0, imag0, real1, imag1, ...]
    float output[1024];
    
    // 填充输入数据
    for (int i = 0; i < 512; i++) {
        input[2*i] = /* 实部 */;
        input[2*i+1] = /* 虚部 */;
    }
    
    // 3. 执行 FFT 变换
    fft_perform_forward(ctx, input, output, 1024);
    
    // 4. 清理资源
    fft_destroy_context(ctx);
    
    return 0;
}
```

### 频谱分析示例

```c
#include "fft_api.h"

int main() {
    FFT_Context* ctx = fft_create_context(256, FFT_TRANSFORM_COMPLEX);
    
    float input[512];      // 256 个复数
    float spectrum[256];   // 频谱输出
    
    // 计算对数幅度谱（dB）
    fft_perform_log_magnitude(ctx, input, spectrum, 512);
    
    // 或计算线性幅度谱
    fft_perform_magnitude(ctx, input, spectrum, 512, 1);
    
    fft_destroy_context(ctx);
    return 0;
}
```

## 📚 API 文档

### 核心函数

| 函数 | 功能 |
|------|------|
| `fft_create_context()` | 创建 FFT 上下文 |
| `fft_destroy_context()` | 销毁 FFT 上下文 |
| `fft_perform_forward()` | 正向复数 FFT |
| `fft_perform_inverse()` | 逆向复数 FFT |
| `fft_perform_real_forward()` | 正向实数 FFT |
| `fft_perform_real_inverse()` | 逆向实数 FFT |

### 频谱分析函数

| 函数 | 功能 |
|------|------|
| `fft_perform_log_magnitude()` | 对数幅度谱（dB） |
| `fft_perform_magnitude()` | 线性幅度谱 |
| `fft_perform_power_spectrum()` | 功率谱 |

### 工具函数

| 函数 | 功能 |
|------|------|
| `fft_get_simd_size()` | 获取 SIMD 向量大小 |
| `fft_aligned_malloc()` | 分配对齐内存 |
| `fft_aligned_free()` | 释放对齐内存 |
| `fft_is_valid_size()` | 检查 FFT 大小是否有效 |

详细 API 文档请参考 [FFT_API_GUIDE.md](FFT_API_GUIDE.md)

## 🎯 支持的 FFT 大小

FFT 大小必须满足：**N = (2^a) × (3^b) × (5^c)**

其中：
- **复数 FFT**：a ≥ 4（最小 16 点），且 N % 16 == 0
- **实数 FFT**：a ≥ 5（最小 32 点），且 N % 32 == 0

### 有效大小示例

✅ **常用大小**：32, 48, 64, 96, 128, 144, 160, 192, 256, 320, 384, 512, 640, 768, 1024, 1536, 2048, 4096

✅ **特殊大小**：
- 1200 = 2⁴ × 3 × 5²
- 1920 = 2⁷ × 3 × 5

### 检查大小有效性

```c
if (fft_is_valid_size(size, FFT_TRANSFORM_COMPLEX)) {
    printf("大小 %d 有效\n", size);
}
```

## ⚡ 性能

PFFFT 在多种平台上都能提供优秀的性能：

- **x86/x64** (SSE)：比 FFTW 快 10-20%
- **ARM** (NEON)：比标量实现快 4-8 倍
- **最佳性能范围**：128 ≤ N ≤ 8192

### 性能优化建议

1. **重用 FFT 上下文**：避免重复创建/销毁
2. **使用对齐内存**：`fft_aligned_malloc()` 获得最佳 SIMD 性能
3. **选择 2 的幂次大小**：64, 128, 256, 512, 1024 等
4. **批处理**：对多个信号使用同一个上下文

## 🔧 构建选项

```bash
# 启用测试
cmake -DBUILD_TESTS=ON ..

# 指定安装路径
cmake -DCMAKE_INSTALL_PREFIX=/usr/local ..

# Release 模式（推荐）
cmake -DCMAKE_BUILD_TYPE=Release ..

# Debug 模式
cmake -DCMAKE_BUILD_TYPE=Debug ..
```

## 📦 安装

### 系统级安装

```bash
cd build
sudo make install
```

安装后文件：
- 库文件：`/usr/local/lib/libpffft.{a,so}`
- 头文件：`/usr/local/include/{pffft.h,fft_api.h}`

### 在项目中使用

```c
#include <fft_api.h>

// 编译时链接
// gcc your_code.c -lpffft -lm -o your_program
```

或在 CMakeLists.txt 中：

```cmake
target_link_libraries(your_program pffft m)
```

## 🐛 已知限制

1. **FFT 大小限制**：必须满足 N=(2^a)×(3^b)×(5^c)
2. **单精度浮点**：仅支持 32 位 float，不支持 double
3. **1D 变换**：仅支持一维 FFT，不支持多维 FFT

## 📖 示例程序

查看 `test/fft_test.c` 获取完整示例：

- ✅ 复数 FFT 正向/逆向变换
- ✅ 实数 FFT 变换
- ✅ 频谱分析（幅度谱、功率谱、对数幅度谱）
- ✅ 工具函数使用

运行测试：

```bash
cd build
./fft_test
```

## 🔗 相关链接

- **PFFFT 原始库**：https://bitbucket.org/jpommier/pffft
- **FFTW**：http://www.fftw.org/
- **FFT 算法介绍**：https://en.wikipedia.org/wiki/Fast_Fourier_transform

## 📄 许可证

本项目基于 PFFFT 库，遵循原项目的许可证。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📞 联系方式

如有问题或建议，请提交 Issue。

---

**版本**：1.0  
**最后更新**：2026年1月5日  
**维护者**：AI Code Assistant