Core Video框架提供的CVPixelBuffer是macOS视频管线中承上启下的核心数据结构，它代表一帧图像在内存中的像素缓冲区。创建Pixel Buffer时传入的属性字典会决定内存布局、颜色解释方式以及能否被GPU或Quartz 2D直接访问。配置不当通常不会立即报错，而是在后续的渲染、编码或显示阶段才暴露出花屏、错位、色偏等问题。
本文围绕创建CVPixelBuffer时需要关注的几类关键属性展开，包括像素格式、宽高、行字节数、颜色空间与扩展像素，并结合C语言示例说明设置方法和验证手段。
一、像素格式与宽高：声明Pixel Buffer的数据布局
Pixel Buffer创建时最基础的两个属性是像素格式和尺寸。像素格式通过kCVPixelBufferPixelFormatTypeKey指定，值是一个四字符代码（FourCC），常见的如kCVPixelFormatType_32BGRA对应BGRA顺序的8位无符号整型分量，kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange则对应双平面YUV 4:2:0视频范围数据。这个代码决定每个像素占用多少字节、通道顺序以及颜色空间隐式约定。宽高分别用kCVPixelBufferWidthKey和kCVPixelBufferHeightKey设置，类型均为CFNumber，单位是像素。这三个键必须同时出现在属性字典中，否则CVPixelBufferCreate会返回kCVReturnInvalidArgument错误。
需要强调的是，宽高是像素数而不是点或逻辑尺寸，在Retina显示器上像素缓冲区通常仍以物理像素为单位。以1920x1080的BGRA帧为例，如果不考虑对齐，理论每行需要1920乘以4等于7680字节。但Core Video会根据像素格式和指定的对齐值调整实际分配和访问步幅，因此宽高只是名义上的图像范围，真实的内存布局必须通过查询bytesPerRow确认。下面的代码展示了创建属性字典并指定像素格式和宽高的过程。
#include <CoreVideo/CoreVideo.h>
#include <CoreFoundation/CoreFoundation.h>
CFMutableDictionaryRef attrs = CFDictionaryCreateMutable(kCFAllocatorDefault, 4,
&kCFTypeDictionaryKeyCallBacks,
&kCFTypeDictionaryValueCallBacks);
uint32_t pixelFormat = kCVPixelFormatType_32BGRA;
int width = 1920;
int height = 1080;
CFNumberRef pfNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &pixelFormat);
CFNumberRef wNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &width);
CFNumberRef hNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &height);
CFDictionarySetValue(attrs, kCVPixelBufferPixelFormatTypeKey, pfNum);
CFDictionarySetValue(attrs, kCVPixelBufferWidthKey, wNum);
CFDictionarySetValue(attrs, kCVPixelBufferHeightKey, hNum);
CFRelease(pfNum);
CFRelease(wNum);
CFRelease(hNum);
CVPixelBufferRef pixelBuffer = NULL;
CVReturn status = CVPixelBufferCreate(kCFAllocatorDefault, width, height, pixelFormat, attrs, &pixelBuffer);
CFRelease(attrs);
if (status != kCVReturnSuccess) {
fprintf(stderr, "CVPixelBufferCreate失败: %d\n", status);
}
// 使用pixelBuffer...
CVPixelBufferRelease(pixelBuffer);
上述代码中CVPixelBufferCreate的第三个和第四个参数与字典中的宽高和像素格式保持一致，这是创建函数的一种便捷方式，实际内部仍以字典为准。如果希望单独修改字典中的宽高而不改函数参数，也可以传入0和0，但那样可读性较差。推荐的做法是两者一致，便于调试。
二、行字节数与内存对齐：避免步幅引起的显示异常
行字节数（bytesPerRow）是图像处理中一个极易被忽略的细节，它表示从一行的第一个像素到下一行第一个像素之间的字节跨度，通常大于或等于宽度乘以每像素字节数。CVPixelBuffer创建时并不直接接受bytesPerRow值，而是通过kCVPixelBufferBytesPerRowAlignmentKey指定对齐要求，系统会在这个对齐基础上计算实际步幅。例如BGRA宽1920理论上每行7680字节，如果对齐到64字节，7680正好是64的倍数，那bytesPerRow就是7680；如果宽度是1921，理论值7684，对齐到64后则变成7680的倍数即7744，多出的60字节作为填充。
对齐值的选择与硬件加速路径有关。Core Animation和Metal通常偏好至少16字节对齐，而某些视频编码器要求64字节甚至128字节对齐。设置过小的对齐值可能导致缓冲区被拒绝，或者复制到GPU时发生额外拷贝；设置过大的对齐值则浪费内存。对于YUV 4:2:0双平面格式，每个平面可能有独立的bytesPerRow，可以用CVPixelBufferGetBytesPerRowOfPlane获取；单平面格式直接使用CVPixelBufferGetBytesPerRow。下面示例设置64字节对齐并查询实际值。
uint32_t alignment = 64;
CFNumberRef alignNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &alignment);
CFDictionarySetValue(attrs, kCVPixelBufferBytesPerRowAlignmentKey, alignNum);
CFRelease(alignNum);
// 创建缓冲区
CVPixelBufferRef buffer = NULL;
CVReturn status = CVPixelBufferCreate(kCFAllocatorDefault, 1921, 1080,
kCVPixelFormatType_32BGRA, attrs, &buffer);
if (status == kCVReturnSuccess) {
size_t actualBytesPerRow = CVPixelBufferGetBytesPerRow(buffer);
printf("宽度1921，对齐64字节后的行字节数: %zu\n", actualBytesPerRow);
// 输出应为7744
CVPixelBufferRelease(buffer);
}
如果后续要把Pixel Buffer的内容复制到CGContext或上传到Metal纹理，务必使用查询到的bytesPerRow而不是用宽度乘以每像素字节数自行计算，否则当缓冲区的对齐填充大于0时，复制操作会读取到错误的偏移，导致画面错位或花屏。很多图像处理库都提供按步幅拷贝的接口，比如memcpy按行执行且每行拷贝实际宽度乘每像素字节数、跳过填充部分。
三、颜色空间与扩展属性：控制色彩转换和边缘像素
像素格式只说明了数据如何排列，并没有完全定义这些数值如何解释成颜色。相同的YUV数据在BT.601和BT.709颜色矩阵下会得到不同的RGB结果，因此需要通过颜色空间附件来补充信息。创建Pixel Buffer时可以使用kCVPixelBufferCGColorSpaceKey在属性字典中设置CGColorSpaceRef对象，该值会被复制到缓冲区的附件中。另一种方式是在创建完成后使用CVBufferSetAttachment把kCVImageBufferCGColorSpaceKey附加到缓冲区，这两种方式都能让Core Image、Video Toolbox等框架正确执行色彩转换。没有设置颜色空间的视频帧可能被默认按设备RGB或视频范围处理，导致颜色饱和度和亮度偏差。
扩展像素属性（ExtendedPixels）主要用于描述有效图像区域四周额外分配的像素。例如图像处理算法需要读取邻域像素时，可以在缓冲区边缘多分配几行或几列，避免边界特判。kCVPixelBufferExtendedPixelsTopKey、kCVPixelBufferExtendedPixelsBottomKey、kCVPixelBufferExtendedPixelsLeftKey、kCVPixelBufferExtendedPixelsRightKey分别指定上、下、左、右的扩展像素数。这些键不会改变CVPixelBufferGetWidth和GetHeight返回的名义宽高，但会增大实际分配的内存和bytesPerRow中的可用空间。有效图像的原点坐标会随左、上扩展量偏移，通过CVPixelBufferGetExtendedPixels可以查询具体数值。
CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB(); CFDictionarySetValue(attrs, kCVPixelBufferCGColorSpaceKey, colorSpace); CGColorSpaceRelease(colorSpace); uint32_t top = 8, bottom = 8, left = 8, right = 8; CFNumberRef topNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &top); CFNumberRef bottomNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &bottom); CFNumberRef leftNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &left); CFNumberRef rightNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &right); CFDictionarySetValue(attrs, kCVPixelBufferExtendedPixelsTopKey, topNum); CFDictionarySetValue(attrs, kCVPixelBufferExtendedPixelsBottomKey, bottomNum); CFDictionarySetValue(attrs, kCVPixelBufferExtendedPixelsLeftKey, leftNum); CFDictionarySetValue(attrs, kCVPixelBufferExtendedPixelsRightKey, rightNum); CFRelease(topNum); CFRelease(bottomNum); CFRelease(leftNum); CFRelease(rightNum);
需要留意的是，扩展像素虽然在内存中存在，但不应该被当作正常图像内容传给显示或编码，除非明确裁剪。例如在将CVPixelBuffer转换为CGImage时，如果使用了扩展像素，得到的图像宽度可能包含填充列，需要根据扩展量裁剪或调整bytesPerRow。因此扩展属性的使用场景相对有限，主要出现在需要手工管理内存布局或与某些底层API对接时；大多数普通视频播放和录制流程可以不设置这些键，让系统自行管理。
四、兼容性开关与完整创建流程：从属性字典到可用缓冲区
除了上述基础属性，还有一些布尔类型的兼容性开关会影响Pixel Buffer的后端存储方式和可访问性。kCVPixelBufferCGImageCompatibilityKey设置为kCFBooleanTrue后，缓冲区可以被CGContext和CGImage直接引用，系统会保证其内存布局符合Quartz 2D的要求；kCVPixelBufferMetalCompatibilityKey打开后，Metal可以通过MTLTexture直接访问缓冲区内容而无需额外拷贝；kCVPixelBufferIOSurfacePropertiesKey则用于把缓冲区托管给IOSurface，实现跨进程共享和GPU零拷贝。在macOS上进行视频采集或渲染时，通常建议至少开启CGImage和Metal兼容性，以便在CPU与GPU之间高效传递。
完整的创建流程需要构建属性字典，设置像素格式、宽高、对齐、颜色空间、兼容性开关，然后调用CVPixelBufferCreate。创建成功后建议查询实际的bytesPerRow、扩展像素以及附件状态，确认与预期一致。下面的代码综合了前述所有设置，并演示了必要的资源释放。创建后的Pixel Buffer可以通过CVPixelBufferLockBaseAddress锁定内存，用CVPixelBufferGetBaseAddress获取首地址后直接读写像素数据，操作完成后解锁。需要特别注意的是，锁定期间不要调用可能改变缓冲区存储的API，例如某些视频编码器可能在内部移动内存。
#include <CoreVideo/CoreVideo.h>
#include <CoreFoundation/CoreFoundation.h>
#include <CoreGraphics/CoreGraphics.h>
#include <stdio.h>
int main(void) {
CFMutableDictionaryRef attrs = CFDictionaryCreateMutable(kCFAllocatorDefault, 16,
&kCFTypeDictionaryKeyCallBacks,
&kCFTypeDictionaryValueCallBacks);
// 像素格式与宽高
uint32_t pixelFormat = kCVPixelFormatType_32BGRA;
int width = 1280;
int height = 720;
CFNumberRef pfNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &pixelFormat);
CFNumberRef wNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &width);
CFNumberRef hNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &height);
CFDictionarySetValue(attrs, kCVPixelBufferPixelFormatTypeKey, pfNum);
CFDictionarySetValue(attrs, kCVPixelBufferWidthKey, wNum);
CFDictionarySetValue(attrs, kCVPixelBufferHeightKey, hNum);
CFRelease(pfNum); CFRelease(wNum); CFRelease(hNum);
// 行字节对齐
uint32_t alignment = 64;
CFNumberRef alignNum = CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &alignment);
CFDictionarySetValue(attrs, kCVPixelBufferBytesPerRowAlignmentKey, alignNum);
CFRelease(alignNum);
// 颜色空间
CGColorSpaceRef colorSpace = CGColorSpaceCreateDeviceRGB();
CFDictionarySetValue(attrs, kCVPixelBufferCGColorSpaceKey, colorSpace);
CGColorSpaceRelease(colorSpace);
// 兼容性
CFDictionarySetValue(attrs, kCVPixelBufferCGImageCompatibilityKey, kCFBooleanTrue);
CFDictionarySetValue(attrs, kCVPixelBufferMetalCompatibilityKey, kCFBooleanTrue);
CFDictionaryRef ioSurfaceProps = CFDictionaryCreate(kCFAllocatorDefault, NULL, NULL, 0,
&kCFTypeDictionaryKeyCallBacks,
&kCFTypeDictionaryValueCallBacks);
CFDictionarySetValue(attrs, kCVPixelBufferIOSurfacePropertiesKey, ioSurfaceProps);
CFRelease(ioSurfaceProps);
// 创建
CVPixelBufferRef pixelBuffer = NULL;
CVReturn status = CVPixelBufferCreate(kCFAllocatorDefault, width, height,
pixelFormat, attrs, &pixelBuffer);
CFRelease(attrs);
if (status != kCVReturnSuccess) {
fprintf(stderr, "创建失败: %d\n", status);
return -1;
}
size_t bytesPerRow = CVPixelBufferGetBytesPerRow(pixelBuffer);
printf("创建成功，行字节数: %zu\n", bytesPerRow);
CVPixelBufferRelease(pixelBuffer);
return 0;
}
属性配置错误最常见的表现是CVPixelBufferCreate返回错误码，或者在后续的CVPixelBufferLockBaseAddress阶段触发内存访问异常。为了避免这些问题，建议把属性字典的构建封装成一个独立函数，并在每次修改像素格式或尺寸后重新生成，因为某些键与特定像素格式不兼容，例如kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange要求宽高为偶数，否则创建可能失败。对于需要动态调整尺寸的场景，可以先尝试用新参数创建，成功后替换旧的Pixel Buffer引用，这样能保持整体管线的稳定性。
Core Video Pixel Buffer像素格式颜色空间修改时间：2026-09-28 01:50:56