Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift

Add the shared vcam CoreMedia data plane and its host harness

Lakr233d8fa40a81282
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 7136faee..7a52e312 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -55,3 +55,8 @@ jobs:
set -euo pipefail
zsh VPhoneExecutable/VPhoneVirtualization/Build/ValidateBundle.sh \
.build/XcodeBundle/Build/Products/Debug/VPhone.bundle
+
+ - name: Guest component tests
+ run: |
+ make -C VPhoneGuestComponents test-loader-links
+ make -C VPhoneGuestComponents test-vcam-dataplane
diff --git a/VPhoneGuestComponents/Makefile b/VPhoneGuestComponents/Makefile
index 2d3cd158..6d1f95c8 100644
--- a/VPhoneGuestComponents/Makefile
+++ b/VPhoneGuestComponents/Makefile
@@ -29,7 +29,7 @@ GPU_PROVENANCE := $(STAGE)/gpu/README.md
# Directory timestamps also catch files removed from the wildcard inputs.
-.PHONY: all gpu package test-loader-links clean
+.PHONY: all gpu package test-loader-links test-vcam-dataplane clean
all: $(ARTIFACTS) $(PLISTS) $(GPU_PROVENANCE)
@@ -46,6 +46,16 @@ test-loader-links:
Tests/RootHideLoaderLinksTests.c Shared/RootHideLoaderLinks.c
@$(OUT)/RootHideLoaderLinksTests
+# Host proof harness for the camera data plane the guest hooks share.
+test-vcam-dataplane:
+ @mkdir -p $(OUT)
+ xcrun --sdk macosx clang -O1 -Wall -Wextra -Werror -Wno-unused-parameter \
+ -o $(OUT)/VCamDataPlaneTests \
+ Tests/VCamDataPlaneTests.c VCamDataPlane/vcam_dataplane.c \
+ -framework CoreMedia -framework CoreVideo -framework CoreFoundation \
+ -framework CoreGraphics
+ @$(OUT)/VCamDataPlaneTests
+
$(STAGE)/camfix $(STAGE)/vcamcaptured $(STAGE)/launchhook $(STAGE)/systemhook $(STAGE)/gpu:
@mkdir -p $@
diff --git a/VPhoneGuestComponents/Tests/VCamDataPlaneTests.c b/VPhoneGuestComponents/Tests/VCamDataPlaneTests.c
new file mode 100644
index 00000000..ad372122
--- /dev/null
+++ b/VPhoneGuestComponents/Tests/VCamDataPlaneTests.c
@@ -0,0 +1,664 @@
+/*
+ * vcam_dataplane_test — host-side proof harness for the shared virtual-
+ * camera data plane (VCamDataPlane/vcam_dataplane.c).
+ *
+ * Builds a synthetic BGRA frame with known color patches, drives it
+ * through the exact chain the guest dylibs use, then dumps everything
+ * reachable from the CVPixelBuffer / CMFormatDescription /
+ * CMSampleBuffer / attachments (the "capture and diff" dump from the
+ * camera-consistency research) and self-verifies:
+ *
+ * 1. advertised format == delivered format ('420v' pixel buffer,
+ * '420v' format description, consistent bytes-per-row)
+ * 2. BT.709 video-range conversion correctness at patch centers
+ * 3. format-description extensions (clean aperture, pixel aspect,
+ * colorimetry) match the bits
+ * 4. timing: host timestamps → monotonic PTS, realistic durations,
+ * stall/burst fallbacks
+ * 5. camera metadata: intrinsic matrix (fx/fy/principal point from
+ * VCC_VCAM_HFOV_DEG), orientation, I-frame provenance
+ * 6. 420v → BGRA round-trip within chroma-subsampling tolerance
+ *
+ * Exit code 0 = all checks pass.
+ *
+ * Build/run: make -C VPhoneGuestComponents test-vcam-dataplane
+ */
+
+#include "../VCamDataPlane/vcam_dataplane.h"
+
+#include <math.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int g_checks = 0;
+static int g_fails = 0;
+
+#define CHECK(cond, ...) \
+ do { \
+ g_checks++; \
+ if (!(cond)) { \
+ g_fails++; \
+ printf(" FAIL: "); \
+ printf(__VA_ARGS__); \
+ printf("\n"); \
+ } \
+ } while (0)
+
+static char vcc4(uint32_t f) { return (char)(f & 0xff); }
+
+static void print_4cc(const char *label, uint32_t f) {
+ printf(" %s = '%c%c%c%c' (0x%08x)\n", label, vcc4(f >> 24), vcc4(f >> 16),
+ vcc4(f >> 8), vcc4(f), f);
+}
+
+// MARK: - synthetic frame
+
+#define TW 1280
+#define TH 720
+#define TBPR (TW * 4) // already 16-byte aligned
+
+typedef struct {
+ uint32_t x, y; // top-left of a 64x64 patch
+ uint8_t b, g, r, a;
+ const char *name;
+} patch_t;
+
+static const patch_t g_patches[] = {
+ {100, 100, 255, 255, 255, 255, "white"},
+ {300, 100, 0, 0, 0, 255, "black"},
+ {500, 100, 0, 0, 255, 255, "red"},
+ {700, 100, 0, 255, 0, 255, "green"},
+ {900, 100, 255, 0, 0, 255, "blue"},
+ {1100, 100, 128, 128, 128, 255, "gray"},
+};
+#define PATCH_COUNT (sizeof(g_patches) / sizeof(g_patches[0]))
+#define PATCH_SIZE 64
+
+static uint8_t *g_frame = NULL;
+
+static void build_test_frame(void) {
+ g_frame = malloc((size_t)TBPR * TH);
+ // Moving-gradient background (like the host test-pattern producer).
+ for (uint32_t y = 0; y < TH; y++) {
+ for (uint32_t x = 0; x < TW; x++) {
+ uint8_t *p = g_frame + (size_t)y * TBPR + x * 4;
+ p[0] = (uint8_t)(x & 0xff); // B
+ p[1] = (uint8_t)((y * 2) & 0xff); // G
+ p[2] = (uint8_t)((x + y) & 0xff); // R
+ p[3] = 255; // A
+ }
+ }
+ for (size_t i = 0; i < PATCH_COUNT; i++) {
+ const patch_t *pt = &g_patches[i];
+ for (uint32_t y = pt->y; y < pt->y + PATCH_SIZE; y++) {
+ uint8_t *row = g_frame + (size_t)y * TBPR;
+ for (uint32_t x = pt->x; x < pt->x + PATCH_SIZE; x++) {
+ uint8_t *p = row + x * 4;
+ p[0] = pt->b;
+ p[1] = pt->g;
+ p[2] = pt->r;
+ p[3] = pt->a;
+ }
+ }
+ }
+}
+
+static const patch_t *find_patch(const char *name) {
+ for (size_t i = 0; i < PATCH_COUNT; i++) {
+ if (!strcmp(g_patches[i].name, name)) return &g_patches[i];
+ }
+ return NULL;
+}
+
+static vcc_frame_desc_t make_desc(uint64_t ts_ns) {
+ vcc_frame_desc_t d = {0};
+ d.width = TW;
+ d.height = TH;
+ d.bytes_per_row = TBPR;
+ d.pixel_format = VCC_FMT_BGRA;
+ d.timestamp_ns = ts_ns;
+ d.frame_index = ts_ns / 33333333ull;
+ d.pixels = g_frame;
+ d.pixels_length = (size_t)TBPR * TH;
+ return d;
+}
+
+// MARK: - dumps
+
+static void dump_pixel_buffer(CVPixelBufferRef pb) {
+ printf(" CVPixelBuffer:\n");
+ printf(" dims = %zux%zu\n", CVPixelBufferGetWidth(pb),
+ CVPixelBufferGetHeight(pb));
+ print_4cc("format", CVPixelBufferGetPixelFormatType(pb));
+ printf(" planeCount = %zu\n", CVPixelBufferGetPlaneCount(pb));
+ if (CVPixelBufferIsPlanar(pb)) {
+ for (size_t p = 0; p < CVPixelBufferGetPlaneCount(pb); p++) {
+ printf(" plane %zu: %zux%zu bpr=%zu base=%p\n", p,
+ CVPixelBufferGetWidthOfPlane(pb, p),
+ CVPixelBufferGetHeightOfPlane(pb, p),
+ CVPixelBufferGetBytesPerRowOfPlane(pb, p),
+ CVPixelBufferGetBaseAddressOfPlane(pb, p));
+ }
+ } else {
+ printf(" bpr = %zu base=%p\n", CVPixelBufferGetBytesPerRow(pb),
+ CVPixelBufferGetBaseAddress(pb));
+ }
+ static const CFStringRef *cvkeys[] = {
+ &kCVImageBufferYCbCrMatrixKey, &kCVImageBufferColorPrimariesKey,
+ &kCVImageBufferTransferFunctionKey};
+ static const char *cvnames[] = {"YCbCrMatrix", "ColorPrimaries",
+ "TransferFunction"};
+ for (int i = 0; i < 3; i++) {
+ CFTypeRef v = CVBufferCopyAttachment(pb, *cvkeys[i], NULL);
+ printf(" attachment %s = %s\n", cvnames[i],
+ v ? CFStringGetCStringPtr(v, kCFStringEncodingUTF8) ?: "?" : "(none)");
+ if (v) CFRelease(v);
+ }
+}
+
+static void dump_format_description(CMVideoFormatDescriptionRef desc) {
+ printf(" CMVideoFormatDescription:\n");
+ print_4cc("mediaSubType", CMFormatDescriptionGetMediaSubType(desc));
+ printf(" dims = %dx%d\n", CMVideoFormatDescriptionGetDimensions(desc).width,
+ CMVideoFormatDescriptionGetDimensions(desc).height);
+ CFDictionaryRef ext = CMFormatDescriptionGetExtensions(desc);
+ printf(" extensions.count = %lu\n",
+ ext ? (unsigned long)CFDictionaryGetCount(ext) : 0);
+ if (ext) {
+ CFStringRef s = CFStringCreateWithFormat(kCFAllocatorDefault, NULL,
+ CFSTR("%@"), ext);
+ char buf[1024];
+ if (CFStringGetCString(s, buf, sizeof(buf), kCFStringEncodingUTF8)) {
+ printf(" extensions = %s\n", buf);
+ }
+ CFRelease(s);
+ }
+ CGRect ca = CMVideoFormatDescriptionGetCleanAperture(desc, true);
+ printf(" cleanAperture = %.0fx%.0f off(%.0f,%.0f)\n", ca.size.width,
+ ca.size.height, ca.origin.x, ca.origin.y);
+}
+
+static void dump_format_description_from_pb(CVPixelBufferRef pb) {
+ CMVideoFormatDescriptionRef desc = NULL;
+ if (vcc_format_description_create_for_pb(pb, &desc) != noErr || !desc) return;
+ dump_format_description(desc);
+ CFRelease(desc);
+}
+
+static void dump_sample_buffer(CMSampleBufferRef sb) {
+ printf(" CMSampleBuffer:\n");
+ CMTime d = CMSampleBufferGetDuration(sb);
+ CMTime p = CMSampleBufferGetPresentationTimeStamp(sb);
+ printf(" numSamples = %lu\n",
+ (unsigned long)CMSampleBufferGetNumSamples(sb));
+ printf(" duration = %.6fs (%lld/%d)\n", CMTimeGetSeconds(d), d.value,
+ d.timescale);
+ printf(" pts = %.6fs (stream-local)\n", CMTimeGetSeconds(p));
+
+ CFArrayRef atts = CMSampleBufferGetSampleAttachmentsArray(sb, true);
+ printf(" attachmentsArray = %s\n", atts ? "(present)" : "(none)");
+
+ CFDataRef intr = CMGetAttachment(
+ sb, kCMSampleBufferAttachmentKey_CameraIntrinsicMatrix, NULL);
+ if (intr && CFDataGetLength(intr) == 36) {
+ const float *m = (const float *)CFDataGetBytePtr(intr);
+ printf(" intrinsicMatrix (column-major) =\n");
+ printf(" [%.2f, %.2f, %.2f]\n", m[0], m[3], m[6]);
+ printf(" [%.2f, %.2f, %.2f]\n", m[1], m[4], m[7]);
+ printf(" [%.2f, %.2f, %.2f]\n", m[2], m[5], m[8]);
+ } else {
+ printf(" intrinsicMatrix = (missing or wrong size: %lu)\n",
+ intr ? (unsigned long)CFDataGetLength(intr) : 0);
+ }
+ CFTypeRef dep = CMGetAttachment(sb, kCMSampleAttachmentKey_DependsOnOthers, NULL);
+ printf(" dependsOnOthers = %s\n",
+ dep == kCFBooleanFalse ? "false (I-frame)" : "?");
+}
+
+// MARK: - test groups
+
+static void test_pixel_values_420v(CVPixelBufferRef pb) {
+ CHECK(CVPixelBufferGetPixelFormatType(pb) == VCC_FMT_420V,
+ "pixel buffer format is not 420v");
+ CHECK(CVPixelBufferGetPlaneCount(pb) == 2, "420v must have 2 planes");
+ CHECK(CVPixelBufferGetWidthOfPlane(pb, 0) == TW &&
+ CVPixelBufferGetHeightOfPlane(pb, 0) == TH,
+ "Y plane dims");
+ CHECK(CVPixelBufferGetWidthOfPlane(pb, 1) == TW / 2 &&
+ CVPixelBufferGetHeightOfPlane(pb, 1) == TH / 2,
+ "CbCr plane dims");
+ CHECK(CVPixelBufferGetBytesPerRowOfPlane(pb, 0) >= TW,
+ "Y bytes-per-row must cover width");
+ CHECK(CVPixelBufferGetBytesPerRowOfPlane(pb, 1) >= TW,
+ "CbCr bytes-per-row must cover 2*(w/2) bytes");
+
+ // Expected BT.709 video-range values at patch centers (chroma from the
+ // 2x2 average — exact for solid patches).
+ struct { const char *name; uint8_t y, cb, cr; } expect[] = {
+ {"white", 235, 128, 128},
+ {"black", 16, 128, 128},
+ {"red", 63, 102, 240}, // Cr clamps at 240
+ {"green", 172, 41, 34},
+ {"blue", 32, 240, 110}, // Cb clamps at 240
+ {"gray", 126, 128, 128},
+ };
+
+ const uint8_t *ybase, *cbase;
+ size_t ybpr, cbpr;
+ CHECK(CVPixelBufferLockBaseAddress(pb, kCVPixelBufferLock_ReadOnly) ==
+ kCVReturnSuccess,
+ "lock 420v planes");
+ ybase = CVPixelBufferGetBaseAddressOfPlane(pb, 0);
+ cbase = CVPixelBufferGetBaseAddressOfPlane(pb, 1);
+ ybpr = CVPixelBufferGetBytesPerRowOfPlane(pb, 0);
+ cbpr = CVPixelBufferGetBytesPerRowOfPlane(pb, 1);
+
+ for (size_t i = 0; i < sizeof(expect) / sizeof(expect[0]); i++) {
+ const patch_t *pt = find_patch(expect[i].name);
+ CHECK(pt != NULL, "patch %s defined in table", expect[i].name);
+ if (!pt) continue;
+ uint32_t sx = pt->x + PATCH_SIZE / 2, sy = pt->y + PATCH_SIZE / 2;
+ uint8_t y = ybase[(size_t)sy * ybpr + sx];
+ uint8_t cb = cbase[(size_t)(sy / 2) * cbpr + (sx / 2) * 2 + 0];
+ uint8_t cr = cbase[(size_t)(sy / 2) * cbpr + (sx / 2) * 2 + 1];
+ int dy = abs((int)y - expect[i].y);
+ int dcb = abs((int)cb - expect[i].cb);
+ int dcr = abs((int)cr - expect[i].cr);
+ printf(" patch %-6s -> Y=%3u (exp %3u d=%d) Cb=%3u (exp %3u d=%d) "
+ "Cr=%3u (exp %3u d=%d)\n",
+ expect[i].name, y, expect[i].y, dy, cb, expect[i].cb, dcb, cr,
+ expect[i].cr, dcr);
+ CHECK(dy <= 1, "%s Y off by %d", expect[i].name, dy);
+ CHECK(dcb <= 2, "%s Cb off by %d", expect[i].name, dcb);
+ CHECK(dcr <= 2, "%s Cr off by %d", expect[i].name, dcr);
+ }
+ CVPixelBufferUnlockBaseAddress(pb, kCVPixelBufferLock_ReadOnly);
+}
+
+static void test_colorimetry_attachments(CVPixelBufferRef pb) {
+ CFStringRef m = CVBufferCopyAttachment(pb, kCVImageBufferYCbCrMatrixKey, NULL);
+ CFStringRef p =
+ CVBufferCopyAttachment(pb, kCVImageBufferColorPrimariesKey, NULL);
+ CFStringRef t =
+ CVBufferCopyAttachment(pb, kCVImageBufferTransferFunctionKey, NULL);
+ CHECK(m && CFEqual(m, kCVImageBufferYCbCrMatrix_ITU_R_709_2),
+ "420v YCbCr matrix must be BT.709");
+ CHECK(p && CFEqual(p, kCVImageBufferColorPrimaries_ITU_R_709_2),
+ "primaries must be BT.709");
+ CHECK(t && CFEqual(t, kCVImageBufferTransferFunction_ITU_R_709_2),
+ "transfer must be BT.709");
+}
+
+static void test_format_description_matches(CVPixelBufferRef pb,
+ int expect_yuv_matrix) {
+ CMVideoFormatDescriptionRef desc = NULL;
+ OSStatus s = vcc_format_description_create_for_pb(pb, &desc);
+ CHECK(s == noErr && desc, "format description creation");
+ if (!desc) return;
+ print_4cc("mediaSubType", CMFormatDescriptionGetMediaSubType(desc));
+ CHECK(CMFormatDescriptionGetMediaSubType(desc) ==
+ (CMVideoCodecType)CVPixelBufferGetPixelFormatType(pb),
+ "format description codec must equal delivered pixel format");
+ CHECK(CMVideoFormatDescriptionGetDimensions(desc).width ==
+ (int32_t)CVPixelBufferGetWidth(pb) &&
+ CMVideoFormatDescriptionGetDimensions(desc).height ==
+ (int32_t)CVPixelBufferGetHeight(pb),
+ "format description dims");
+ CHECK(CMVideoFormatDescriptionMatchesImageBuffer(desc, pb) != 0,
+ "description must pass CMVideoFormatDescriptionMatchesImageBuffer");
+
+ CFDictionaryRef ext = CMFormatDescriptionGetExtensions(desc);
+ CHECK(ext != NULL, "format description must carry extensions");
+ if (ext) {
+ CFTypeRef v;
+ // Attachments are folded in under the CV-prefixed canonical names.
+ v = CFDictionaryGetValue(ext, CFSTR("CVCleanAperture"));
+ CHECK(v != NULL, "clean aperture inherited from pixel buffer");
+ v = CFDictionaryGetValue(ext, CFSTR("CVPixelAspectRatio"));
+ CHECK(v != NULL, "pixel aspect ratio inherited from pixel buffer");
+ v = CFDictionaryGetValue(ext, CFSTR("CVImageBufferColorPrimaries"));
+ CHECK(v && CFEqual(v, kCVImageBufferColorPrimaries_ITU_R_709_2),
+ "709 primaries in extensions");
+ v = CFDictionaryGetValue(ext, CFSTR("CVImageBufferYCbCrMatrix"));
+ if (expect_yuv_matrix) {
+ CHECK(v && CFEqual(v, kCVImageBufferYCbCrMatrix_ITU_R_709_2),
+ "709 YCbCr matrix in extensions");
+ } else {
+ CHECK(v == NULL, "BGRA extensions must not claim a YCbCr matrix");
+ }
+ }
+
+ CGRect ca = CMVideoFormatDescriptionGetCleanAperture(desc, true);
+ CHECK((int)ca.size.width == TW && (int)ca.size.height == TH &&
+ ca.origin.x == 0 && ca.origin.y == 0,
+ "clean aperture = full frame");
+
+ CFRelease(desc);
+}
+
+static void test_timing(void) {
+ vcc_timing_state_t st;
+ vcc_timing_init(&st);
+ CMTime pts, dur;
+
+ uint64_t t0 = 1726500000ull * 1000000000ull; // host wall-clock epoch ns
+ struct { uint64_t dt_ns; double want_pts_s, want_dur_s; } steps[] = {
+ {0, 0.0, 1.0 / 30.0}, // first frame
+ {33400000, 0.0334, 0.0334}, // normal cadence
+ {33300000, 0.0667, 0.0333}, // normal cadence
+ {500000000, 0.5667, 1.0 / 30.0}, // stall -> fallback duration
+ {0, 0.5667 + 0.033333333, 1.0 / 30.0}, // duplicate tick -> still advances
+ };
+ uint64_t ts = t0;
+ double last_pts = -1.0;
+ for (size_t i = 0; i < sizeof(steps) / sizeof(steps[0]); i++) {
+ ts += steps[i].dt_ns;
+ vcc_timing_advance(&st, ts, &pts, &dur);
+ double p = CMTimeGetSeconds(pts);
+ double d = CMTimeGetSeconds(dur);
+ printf(" host_ts=%llu pts=%.6fs dur=%.6fs\n",
+ (unsigned long long)ts, p, d);
+ CHECK(p > last_pts, "pts strictly increasing (frame %zu)", i);
+ CHECK(fabs(p - steps[i].want_pts_s) < 1e-4, "pts value frame %zu", i);
+ CHECK(fabs(d - steps[i].want_dur_s) < 1e-4, "duration frame %zu", i);
+ last_pts = p;
+ }
+}
+
+static void test_cmsb_metadata(CMSampleBufferRef sb) {
+ // Timing on the buffer itself.
+ double dur = CMTimeGetSeconds(CMSampleBufferGetDuration(sb));
+ double pts = CMTimeGetSeconds(CMSampleBufferGetPresentationTimeStamp(sb));
+ CHECK(CMSampleBufferGetNumSamples(sb) == 1, "one sample per buffer");
+ CHECK(fabs(dur - 1.0 / 30.0) < 0.001, "duration ~1/30s, got %.6f", dur);
+ CHECK(pts >= 0.0, "stream-local pts non-negative");
+
+ // Intrinsic matrix.
+ CFDataRef intr = CMGetAttachment(
+ sb, kCMSampleBufferAttachmentKey_CameraIntrinsicMatrix, NULL);
+ CHECK(intr != NULL, "intrinsic matrix attachment present");
+ CHECK(intr && CFDataGetLength(intr) == 36, "intrinsic matrix is 9 floats");
+ if (intr && CFDataGetLength(intr) == 36) {
+ const float *m = (const float *)CFDataGetBytePtr(intr);
+ double want_fx = (0.5 * TW) / tan(VCC_VCAM_HFOV_DEG * M_PI / 360.0);
+ printf(" fx=fy=%.2f (want %.2f from HFOV %.1f deg) ox=%.1f oy=%.1f\n",
+ m[0], want_fx, VCC_VCAM_HFOV_DEG, m[6], m[7]);
+ CHECK(fabs(m[0] - want_fx) < 0.5, "fx matches HFOV derivation");
+ CHECK(m[1] == 0 && m[2] == 0 && m[3] == 0 && m[5] == 0 && m[8] == 1,
+ "zero skew/aspect entries");
+ CHECK(fabs(m[6] - TW / 2.0) < 0.01 && fabs(m[7] - TH / 2.0) < 0.01,
+ "principal point at frame center");
+ CHECK(fabs(m[4] - want_fx) < 0.5, "fy matches fx (square pixels)");
+ }
+
+ // Orientation + provenance.
+ CFStringRef ok = CFSTR("Orientation");
+ CFTypeRef orient = CMGetAttachment(sb, ok, NULL);
+ CHECK(orient != NULL, "orientation attachment present");
+ if (orient) {
+ long o = -1;
+ if (CFGetTypeID(orient) == CFNumberGetTypeID()) {
+ CFNumberGetValue((CFNumberRef)orient, kCFNumberLongType, &o);
+ } else if (CFGetTypeID(orient) == CFStringGetTypeID()) {
+ o = CFStringGetIntValue((CFStringRef)orient);
+ }
+ CHECK(o == 1, "orientation == 1 (landscape-native), got %ld", o);
+ }
+ CFTypeRef dep =
+ CMGetAttachment(sb, kCMSampleAttachmentKey_DependsOnOthers, NULL);
+ CHECK(dep == kCFBooleanFalse, "dependsOnOthers == false (I-frame)");
+}
+
+static void test_roundtrip(void) {
+ // Build the 420v pixel buffer, then re-serialize its planes into a wire
+ // frame and decode back to tight BGRA through the shared helper.
+ vcc_frame_desc_t src = make_desc(1000000000ull);
+ CVPixelBufferRef pb = vcc_pixel_buffer_from_frame(&src, VCC_FMT_420V);
+ CHECK(pb != NULL, "420v buffer for round-trip");
+ if (!pb) return;
+ CVPixelBufferLockBaseAddress(pb, 0);
+
+ size_t ybpr = CVPixelBufferGetBytesPerRowOfPlane(pb, 0);
+ size_t cbpr = CVPixelBufferGetBytesPerRowOfPlane(pb, 1);
+ size_t wire_len = ybpr * TH + cbpr * (TH / 2);
+ uint8_t *wire = malloc(wire_len);
+ memcpy(wire, CVPixelBufferGetBaseAddressOfPlane(pb, 0), ybpr * TH);
+ memcpy(wire + ybpr * TH, CVPixelBufferGetBaseAddressOfPlane(pb, 1),
+ cbpr * (TH / 2));
+ CVPixelBufferUnlockBaseAddress(pb, 0);
+ CVPixelBufferRelease(pb);
+
+ vcc_frame_desc_t yuv = make_desc(1000000000ull);
+ yuv.pixel_format = VCC_FMT_420V;
+ yuv.bytes_per_row = (uint32_t)ybpr;
+ yuv.bytes_per_row1 = (uint32_t)cbpr;
+ yuv.pixels = wire;
+ yuv.pixels_length = wire_len;
+
+ uint8_t *bgra = NULL;
+ uint32_t bpr = 0;
+ int rc = vcc_bgra_bytes_from_frame(&yuv, &bgra, &bpr);
+ CHECK(rc == 0 && bgra && bpr == TW * 4, "420v -> BGRA decode");
+ if (rc != 0 || !bgra) {
+ free(wire);
+ return;
+ }
+
+ for (size_t i = 0; i < PATCH_COUNT; i++) {
+ const patch_t *pt = &g_patches[i];
+ uint32_t sx = pt->x + PATCH_SIZE / 2, sy = pt->y + PATCH_SIZE / 2;
+ const uint8_t *p = bgra + (size_t)sy * bpr + sx * 4;
+ int db = abs((int)p[0] - pt->b), dg = abs((int)p[1] - pt->g),
+ dr = abs((int)p[2] - pt->r);
+ printf(" round-trip %-6s -> B=%3u G=%3u R=%3u (delta %d/%d/%d)\n",
+ pt->name, p[0], p[1], p[2], db, dg, dr);
+ // 8-bit studio-swing 4:2:0 chroma quantization: pure primaries round-trip
+ // with up to ~16 levels of crosstalk (same as real camera 420v output).
+ CHECK(db <= 16 && dg <= 16 && dr <= 16,
+ "%s round-trip within chroma tolerance", pt->name);
+ }
+ free(bgra);
+ free(wire);
+}
+
+// MARK: - phase 3/4 checks
+
+static void test_cgimage_helper(void) {
+ printf(" [4a] pixel buffer -> CGImage (preview/photo path)\n");
+ vcc_frame_desc_t frame = make_desc(1000000000ull);
+
+ // BGRA: bit-exact.
+ CVPixelBufferRef pb = vcc_pixel_buffer_from_frame(&frame, VCC_FMT_BGRA);
+ CHECK(pb != NULL, "BGRA pb for CGImage");
+ if (pb) {
+ CGImageRef img = vcc_cgimage_from_pixel_buffer(pb);
+ CHECK(img != NULL, "CGImage from BGRA pb");
+ if (img) {
+ CHECK(CGImageGetWidth(img) == TW && CGImageGetHeight(img) == TH,
+ "CGImage dims match");
+ CHECK(CGImageGetBitsPerPixel(img) == 32, "CGImage 32bpp");
+ // Sample the red patch center out of the CGImage's provider.
+ CGDataProviderRef dp = CGImageGetDataProvider(img);
+ CFDataRef data = dp ? CGDataProviderCopyData(dp) : NULL;
+ if (data) {
+ const uint8_t *bytes = CFDataGetBytePtr(data);
+ size_t rbpr = CGImageGetBytesPerRow(img);
+ const patch_t *pt = find_patch("blue");
+ const uint8_t *p = bytes + (size_t)(pt->y + 32) * rbpr + (pt->x + 32) * 4;
+ CHECK(p[0] == 255 && p[1] == 0 && p[2] == 0,
+ "CGImage pixel at blue patch is blue (B=%u G=%u R=%u)",
+ p[0], p[1], p[2]);
+ CFRelease(data);
+ }
+ CGImageRelease(img);
+ }
+ CVPixelBufferRelease(pb);
+ }
+
+ // 420v: patches preserved within chroma quantization.
+ pb = vcc_pixel_buffer_from_frame(&frame, VCC_FMT_420V);
+ CHECK(pb != NULL, "420v pb for CGImage");
+ if (pb) {
+ CGImageRef img = vcc_cgimage_from_pixel_buffer(pb);
+ CHECK(img != NULL, "CGImage from 420v pb");
+ if (img) {
+ CGDataProviderRef dp = CGImageGetDataProvider(img);
+ CFDataRef data = dp ? CGDataProviderCopyData(dp) : NULL;
+ if (data) {
+ const uint8_t *bytes = CFDataGetBytePtr(data);
+ size_t rbpr = CGImageGetBytesPerRow(img);
+ const patch_t *pt = find_patch("white");
+ const uint8_t *p = bytes + (size_t)(pt->y + 32) * rbpr + (pt->x + 32) * 4;
+ CHECK(p[0] >= 245 && p[1] >= 245 && p[2] >= 245,
+ "white patch survives 420v -> CGImage (%u/%u/%u)",
+ p[0], p[1], p[2]);
+ CFRelease(data);
+ }
+ CGImageRelease(img);
+ }
+ CVPixelBufferRelease(pb);
+ }
+}
+
+static void test_format_metadata_consistency(void) {
+ // Phase 3 contract: the published format keys and the delivered sample
+ // buffer must tell one story. These mirror what the synthetic source
+ // publishes in libvcamcaptured (VideoFieldOfView = VCC_VCAM_HFOV_DEG,
+ // CameraCalibrationDataDeliverySupported = YES).
+ printf(" [4b] published-format <-> delivered-sample consistency\n");
+ vcc_timing_state_t timing;
+ vcc_timing_init(&timing);
+ vcc_frame_desc_t frame = make_desc(1726500000ull * 1000000000ull);
+
+ CMSampleBufferRef sb = vcc_cmsb_from_frame(&frame, VCC_FMT_420V, &timing);
+ CHECK(sb != NULL, "sample for consistency check");
+ if (!sb) return;
+ CMVideoFormatDescriptionRef desc = CMSampleBufferGetFormatDescription(sb);
+
+ // Delivered codec == advertised PixelFormatType (420v active format).
+ CHECK(CMFormatDescriptionGetMediaSubType(desc) == (CMVideoCodecType)VCC_FMT_420V,
+ "delivered codec matches advertised active format");
+ // Delivered dimensions == advertised Width/Height.
+ CHECK(CMVideoFormatDescriptionGetDimensions(desc).width == TW &&
+ CMVideoFormatDescriptionGetDimensions(desc).height == TH,
+ "delivered dims match advertised dims");
+ // Intrinsic focal length == what videoFieldOfView=63.0 implies.
+ CFDataRef intr = CMGetAttachment(
+ sb, kCMSampleBufferAttachmentKey_CameraIntrinsicMatrix, NULL);
+ CHECK(intr && CFDataGetLength(intr) == 36, "intrinsics present");
+ if (intr) {
+ const float *m = (const float *)CFDataGetBytePtr(intr);
+ double want_fx = (0.5 * TW) / tan(VCC_VCAM_HFOV_DEG * M_PI / 360.0);
+ CHECK(fabs(m[0] - want_fx) < 0.5,
+ "fx=%.2f consistent with advertised FOV %.1f deg", m[0],
+ VCC_VCAM_HFOV_DEG);
+ }
+ CFRelease(sb);
+
+ // One pipeline: CGImage derivation from the SAME sample's pixel buffer
+ // (what the Phase 4 preview pump consumes) matches the wire frame.
+ CVPixelBufferRef pb = vcc_pixel_buffer_from_frame(&frame, VCC_FMT_420V);
+ if (pb) {
+ CGImageRef img = vcc_cgimage_from_pixel_buffer(pb);
+ CHECK(img != NULL, "preview-pipeline CGImage");
+ if (img) CGImageRelease(img);
+ CVPixelBufferRelease(pb);
+ }
+}
+
+static void test_full_chain_dump(void) {
+ vcc_timing_state_t timing;
+ vcc_timing_init(&timing);
+ vcc_frame_desc_t frame = make_desc(1726500000ull * 1000000000ull);
+ frame.frame_index = 42;
+
+ printf(" -- chain: BGRA host frame -> '420v' camera sample --\n");
+ CMSampleBufferRef sb = vcc_cmsb_from_frame(&frame, VCC_FMT_420V, &timing);
+ CHECK(sb != NULL, "vcc_cmsb_from_frame 420v");
+ if (!sb) return;
+ CVPixelBufferRef pb = CMSampleBufferGetImageBuffer(sb);
+ CHECK(pb != NULL, "sample buffer carries image buffer");
+ CMVideoFormatDescriptionRef desc =
+ CMSampleBufferGetFormatDescription(sb);
+ CHECK(desc != NULL, "sample buffer carries format description");
+ if (pb) dump_pixel_buffer(pb);
+ if (desc) dump_format_description(desc);
+ dump_sample_buffer(sb);
+ if (pb) test_pixel_values_420v(pb);
+ if (pb) test_colorimetry_attachments(pb);
+ test_cmsb_metadata(sb);
+ CFRelease(sb);
+
+ printf(" -- chain: BGRA host frame -> BGRA camera sample --\n");
+ vcc_timing_init(&timing);
+ sb = vcc_cmsb_from_frame(&frame, VCC_FMT_BGRA, &timing);
+ CHECK(sb != NULL, "vcc_cmsb_from_frame bgra");
+ if (!sb) return;
+ pb = CMSampleBufferGetImageBuffer(sb);
+ CHECK(pb && CVPixelBufferGetPixelFormatType(pb) == VCC_FMT_BGRA,
+ "BGRA delivered as BGRA");
+ CHECK(pb && CVPixelBufferGetBytesPerRow(pb) >= TW * 4, "BGRA bpr sane");
+ dump_pixel_buffer(pb);
+ if (pb) {
+ CHECK(CVPixelBufferLockBaseAddress(pb, kCVPixelBufferLock_ReadOnly) ==
+ kCVReturnSuccess,
+ "lock BGRA base");
+ const uint8_t *base = CVPixelBufferGetBaseAddress(pb);
+ const patch_t *pt = find_patch("red");
+ const uint8_t *p = base + (size_t)(pt->y + 32) * CVPixelBufferGetBytesPerRow(pb) +
+ (pt->x + 32) * 4;
+ CHECK(p[2] == 255 && p[0] == 0 && p[1] == 0 && p[3] == 255,
+ "BGRA passthrough bit-exact at red patch");
+ CVPixelBufferUnlockBaseAddress(pb, kCVPixelBufferLock_ReadOnly);
+ }
+ test_cmsb_metadata(sb);
+ CFRelease(sb);
+}
+
+int main(void) {
+ printf("vcam data-plane proof harness\n");
+ printf("=============================\n\n");
+
+ build_test_frame();
+
+ printf("[1] timing state machine\n");
+ test_timing();
+ printf(" ok\n\n");
+
+ printf("[2] format descriptions from pixel buffers\n");
+ {
+ vcc_frame_desc_t frame = make_desc(1000000000ull);
+ CVPixelBufferRef pb420 = vcc_pixel_buffer_from_frame(&frame, VCC_FMT_420V);
+ CVPixelBufferRef pbbgra = vcc_pixel_buffer_from_frame(&frame, VCC_FMT_BGRA);
+ CHECK(pb420 && pbbgra, "pixel buffers for format-description tests");
+ if (pb420) {
+ test_format_description_matches(pb420, 1);
+ dump_format_description_from_pb(pb420);
+ CVPixelBufferRelease(pb420);
+ }
+ if (pbbgra) {
+ test_format_description_matches(pbbgra, 0);
+ CVPixelBufferRelease(pbbgra);
+ }
+ }
+ printf(" ok\n\n");
+
+ printf("[3] full chains + reachable-state dump\n");
+ test_full_chain_dump();
+ printf(" ok\n\n");
+
+ printf("[4] 420v -> BGRA round trip\n");
+ test_roundtrip();
+ printf(" ok\n\n");
+
+ printf("[5] phase 3/4: CGImage path + format/sample consistency\n");
+ test_cgimage_helper();
+ test_format_metadata_consistency();
+ printf(" ok\n\n");
+
+ printf("=============================\n");
+ printf("%d checks, %d failures\n", g_checks, g_fails);
+ free(g_frame);
+ return g_fails ? 1 : 0;
+}
diff --git a/VPhoneGuestComponents/VCamDataPlane/vcam_dataplane.c b/VPhoneGuestComponents/VCamDataPlane/vcam_dataplane.c
new file mode 100644
index 00000000..43785697
--- /dev/null
+++ b/VPhoneGuestComponents/VCamDataPlane/vcam_dataplane.c
@@ -0,0 +1,573 @@
+/*
+ * vcam_dataplane — see vcam_dataplane.h for the design contract.
+ */
+
+#include "vcam_dataplane.h"
+
+#include <dlfcn.h>
+#include <math.h>
+#include <stdlib.h>
+#include <string.h>
+
+// MARK: - constants (private)
+
+#define VCC_DUR_DEFAULT_NS 33333333ull // 1/30 s
+#define VCC_DUR_MIN_NS 4000000ull // 4 ms — below this, treat as burst
+#define VCC_DUR_MAX_NS 200000000ull // 200 ms — above this, treat as stall
+#define VCC_PARAM_ERR (-50) // paramErr, avoids Carbon include
+
+// kCGImagePropertyOrientation lives in ImageIO; the key string is stable.
+// Resolve the public constant when available; the literal fallback keeps us
+// independent of ImageIO link order.
+static CFStringRef vcc_orientation_key(void) {
+ CFStringRef *slot =
+ (CFStringRef *)dlsym(RTLD_DEFAULT, "kCGImagePropertyOrientation");
+ return (slot && *slot) ? *slot : CFSTR("Orientation");
+}
+
+// MARK: - timing
+
+void vcc_timing_init(vcc_timing_state_t *st) {
+ memset(st, 0, sizeof(*st));
+}
+
+void vcc_timing_advance(vcc_timing_state_t *st, uint64_t host_ts_ns,
+ CMTime *out_pts, CMTime *out_dur) {
+ uint64_t pts;
+ if (!st->have_last) {
+ // First frame: anchor the stream-local timeline at zero.
+ st->anchor_ns = host_ts_ns;
+ st->last_host_ns = host_ts_ns;
+ st->last_dur_ns = VCC_DUR_DEFAULT_NS;
+ st->have_last = 1;
+ pts = 0;
+ } else {
+ uint64_t delta = host_ts_ns - st->last_host_ns; // wraps safely
+ if (delta >= VCC_DUR_MIN_NS && delta <= VCC_DUR_MAX_NS) {
+ st->last_dur_ns = delta;
+ } else {
+ st->last_dur_ns = VCC_DUR_DEFAULT_NS;
+ }
+ if (host_ts_ns > st->last_host_ns) {
+ st->last_host_ns = host_ts_ns;
+ }
+ // Stream-local PTS: host epoch remapped by the anchor. Never go
+ // backwards; a non-advancing host clock still produces an advancing
+ // timeline (the viewfinder jitter buffer drops non-advancing PTS).
+ pts = host_ts_ns - st->anchor_ns;
+ if (pts <= st->last_pts_ns) {
+ pts = st->last_pts_ns + st->last_dur_ns;
+ }
+ }
+ st->last_pts_ns = pts;
+
+ if (out_pts) {
+ *out_pts = CMTimeMake((int64_t)pts, 1000000000);
+ }
+ if (out_dur) {
+ *out_dur = CMTimeMake((int64_t)st->last_dur_ns, 1000000000);
+ }
+}
+
+// MARK: - pixel conversion
+
+int vcc_is_planar_yuv(uint32_t fourcc) {
+ return fourcc == VCC_FMT_420V || fourcc == VCC_FMT_420F;
+}
+
+static inline uint8_t vcc_clamp8(int v) {
+ if (v < 0) return 0;
+ if (v > 255) return 255;
+ return (uint8_t)v;
+}
+
+// BT.709 video-range encode of one pixel. Coefficients (scaled by 256):
+// Y = 16 + (47R + 157G + 16B) >> 8 [16..235]
+// Cb = 128 + (-26R - 87G + 113B) >> 8 [16..240]
+// Cr = 128 + (112R - 94G - 18B) >> 8 [16..240]
+static inline void vcc_rgb_to_yuv709v(uint8_t r, uint8_t g, uint8_t b,
+ uint8_t *y, uint8_t *cb, uint8_t *cr) {
+ int yy = 16 + (((47 * r + 157 * g + 16 * b) + 128) >> 8);
+ int cu = 128 + (((-26 * r - 87 * g + 113 * b) + 128) >> 8);
+ int cv = 128 + (((112 * r - 94 * g - 18 * b) + 128) >> 8);
+ if (yy < 16) yy = 16; else if (yy > 235) yy = 235;
+ if (cu < 16) cu = 16; else if (cu > 240) cu = 240;
+ if (cv < 16) cv = 16; else if (cv > 240) cv = 240;
+ *y = (uint8_t)yy;
+ *cb = (uint8_t)cu;
+ *cr = (uint8_t)cv;
+}
+
+// BT.709 video-range decode.
+static inline void vcc_yuv709v_to_rgb(uint8_t y, uint8_t cb, uint8_t cr,
+ uint8_t *r, uint8_t *g, uint8_t *b) {
+ int yy = (int)y - 16;
+ int u = (int)cb - 128;
+ int v = (int)cr - 128;
+ int rr = (298 * yy + 459 * v + 128) >> 8;
+ int gg = (298 * yy - 55 * u - 136 * v + 128) >> 8;
+ int bb = (298 * yy + 541 * u + 128) >> 8;
+ *r = vcc_clamp8(rr);
+ *g = vcc_clamp8(gg);
+ *b = vcc_clamp8(bb);
+}
+
+// BGRA (stride src_bpr) → interleaved 420v planes. Y gets per-pixel stride
+// dst_y_bpr; CbCr gets 2-byte macropixels at dst_c_bpr.
+static void vcc_bgra_to_420v(const uint8_t *src, uint32_t src_bpr,
+ uint32_t w, uint32_t h,
+ uint8_t *dst_y, uint32_t dst_y_bpr,
+ uint8_t *dst_c, uint32_t dst_c_bpr) {
+ uint32_t cw = w / 2;
+ uint32_t ch = h / 2;
+ for (uint32_t cy = 0; cy < ch; cy++) {
+ const uint8_t *row0 = src + (size_t)(cy * 2) * src_bpr;
+ const uint8_t *row1 = row0 + src_bpr;
+ uint8_t *yrow0 = dst_y + (size_t)(cy * 2) * dst_y_bpr;
+ uint8_t *yrow1 = yrow0 + dst_y_bpr;
+ uint8_t *crow = dst_c + (size_t)cy * dst_c_bpr;
+ for (uint32_t cx = 0; cx < cw; cx++) {
+ uint32_t x0 = cx * 2;
+ // 2x2 RGB average for chroma (rounding divide by 4).
+ uint32_t b00 = row0[x0 * 4 + 0], g00 = row0[x0 * 4 + 1];
+ uint32_t r00 = row0[x0 * 4 + 2];
+ uint32_t b01 = row0[(x0 + 1) * 4 + 0], g01 = row0[(x0 + 1) * 4 + 1];
+ uint32_t r01 = row0[(x0 + 1) * 4 + 2];
+ uint32_t b10 = row1[x0 * 4 + 0], g10 = row1[x0 * 4 + 1];
+ uint32_t r10 = row1[x0 * 4 + 2];
+ uint32_t b11 = row1[(x0 + 1) * 4 + 0], g11 = row1[(x0 + 1) * 4 + 1];
+ uint32_t r11 = row1[(x0 + 1) * 4 + 2];
+ uint8_t y0, y1, y2, y3, cb, cr, ytmp;
+ // Chroma from the 2x2 RGB average (chroma subsampling), luma per pixel.
+ vcc_rgb_to_yuv709v((uint8_t)((r00 + r01 + r10 + r11 + 2) >> 2),
+ (uint8_t)((g00 + g01 + g10 + g11 + 2) >> 2),
+ (uint8_t)((b00 + b01 + b10 + b11 + 2) >> 2),
+ &ytmp, &cb, &cr);
+ vcc_rgb_to_yuv709v(r00, g00, b00, &y0, &ytmp, &ytmp);
+ vcc_rgb_to_yuv709v(r01, g01, b01, &y1, &ytmp, &ytmp);
+ vcc_rgb_to_yuv709v(r10, g10, b10, &y2, &ytmp, &ytmp);
+ vcc_rgb_to_yuv709v(r11, g11, b11, &y3, &ytmp, &ytmp);
+ yrow0[x0] = y0;
+ yrow0[x0 + 1] = y1;
+ yrow1[x0] = y2;
+ yrow1[x0 + 1] = y3;
+ crow[cx * 2 + 0] = cb; // Cb
+ crow[cx * 2 + 1] = cr; // Cr
+ }
+ // Odd width: last column is luma-only; leave chroma from column cw-1.
+ if (w & 1u) {
+ uint32_t x0 = w - 1;
+ uint8_t y0, cb, cr;
+ vcc_rgb_to_yuv709v(row0[x0 * 4 + 2], row0[x0 * 4 + 1], row0[x0 * 4 + 0],
+ &y0, &cb, &cr);
+ yrow0[x0] = y0;
+ vcc_rgb_to_yuv709v(row1[x0 * 4 + 2], row1[x0 * 4 + 1], row1[x0 * 4 + 0],
+ &y0, &cb, &cr);
+ yrow1[x0] = y0;
+ }
+ }
+ // Odd height: last row is luma-only.
+ if (h & 1u) {
+ const uint8_t *row = src + (size_t)(h - 1) * src_bpr;
+ uint8_t *yrow = dst_y + (size_t)(h - 1) * dst_y_bpr;
+ for (uint32_t x = 0; x < w; x++) {
+ uint8_t y0, cb, cr;
+ vcc_rgb_to_yuv709v(row[x * 4 + 2], row[x * 4 + 1], row[x * 4 + 0],
+ &y0, &cb, &cr);
+ yrow[x] = y0;
+ }
+ }
+}
+
+// Interleaved 420v planes → BGRA (tight stride).
+static void vcc_420v_to_bgra(const uint8_t *src_y, uint32_t src_y_bpr,
+ const uint8_t *src_c, uint32_t src_c_bpr,
+ uint32_t w, uint32_t h,
+ uint8_t *dst, uint32_t dst_bpr) {
+ for (uint32_t y = 0; y < h; y++) {
+ const uint8_t *yrow = src_y + (size_t)y * src_y_bpr;
+ const uint8_t *crow = src_c + (size_t)(y / 2) * src_c_bpr;
+ uint8_t *drow = dst + (size_t)y * dst_bpr;
+ for (uint32_t x = 0; x < w; x++) {
+ uint8_t cb = crow[(x / 2) * 2 + 0];
+ uint8_t cr = crow[(x / 2) * 2 + 1];
+ uint8_t r, g, b;
+ vcc_yuv709v_to_rgb(yrow[x], cb, cr, &r, &g, &b);
+ drow[x * 4 + 0] = b;
+ drow[x * 4 + 1] = g;
+ drow[x * 4 + 2] = r;
+ drow[x * 4 + 3] = 255;
+ }
+ }
+}
+
+// MARK: - pixel buffers
+
+static void vcc_release_malloc_bytes(void *refcon, const void *baseAddress) {
+ (void)refcon;
+ free((void *)baseAddress);
+}
+
+// Same free, CGDataProviderReleaseDataCallback shape.
+static void vcc_cg_release_data(void *refcon, const void *data, size_t size) {
+ (void)data;
+ (void)size;
+ free((void *)refcon);
+}
+
+/*
+ * Camera image-buffer attachments. These are what makes the pixel buffer
+ * (and, transitively, the CMVideoFormatDescription built from it via
+ * CreateForImageBuffer) tell the same story as the pixels:
+ * - BT.709 primaries/transfer, plus YCbCr matrix for 4:2:0
+ * - clean aperture = full frame (no sensor-edge padding to crop away)
+ * - pixel aspect ratio 1:1 (square pixels)
+ */
+static void vcc_attach_camera_metadata(CVPixelBufferRef pb, int is_yuv) {
+ CVBufferSetAttachment(
+ pb, kCVImageBufferColorPrimariesKey,
+ kCVImageBufferColorPrimaries_ITU_R_709_2,
+ kCVAttachmentMode_ShouldPropagate);
+ CVBufferSetAttachment(
+ pb, kCVImageBufferTransferFunctionKey,
+ kCVImageBufferTransferFunction_ITU_R_709_2,
+ kCVAttachmentMode_ShouldPropagate);
+ if (is_yuv) {
+ CVBufferSetAttachment(pb, kCVImageBufferYCbCrMatrixKey,
+ kCVImageBufferYCbCrMatrix_ITU_R_709_2,
+ kCVAttachmentMode_ShouldPropagate);
+ }
+
+ int32_t w = (int32_t)CVPixelBufferGetWidth(pb);
+ int32_t h = (int32_t)CVPixelBufferGetHeight(pb);
+ int32_t zero = 0, one = 1;
+ CFNumberRef clean_w =
+ CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &w);
+ CFNumberRef clean_h =
+ CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &h);
+ CFNumberRef clean_x =
+ CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &zero);
+ CFNumberRef clean_y =
+ CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &zero);
+ const void *clean_keys[] = {
+ kCVImageBufferCleanApertureWidthKey,
+ kCVImageBufferCleanApertureHeightKey,
+ kCVImageBufferCleanApertureHorizontalOffsetKey,
+ kCVImageBufferCleanApertureVerticalOffsetKey,
+ };
+ const void *clean_vals[] = {clean_w, clean_h, clean_x, clean_y};
+ CFDictionaryRef clean_aperture = CFDictionaryCreate(
+ kCFAllocatorDefault, clean_keys, clean_vals, 4, NULL, NULL);
+ CVBufferSetAttachment(pb, kCVImageBufferCleanApertureKey, clean_aperture,
+ kCVAttachmentMode_ShouldPropagate);
+ CFRelease(clean_aperture);
+ CFRelease(clean_w);
+ CFRelease(clean_h);
+ CFRelease(clean_x);
+ CFRelease(clean_y);
+
+ CFNumberRef par_h =
+ CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &one);
+ CFNumberRef par_v =
+ CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &one);
+ const void *par_keys[] = {
+ kCVImageBufferPixelAspectRatioHorizontalSpacingKey,
+ kCVImageBufferPixelAspectRatioVerticalSpacingKey,
+ };
+ const void *par_vals[] = {par_h, par_v};
+ CFDictionaryRef par =
+ CFDictionaryCreate(kCFAllocatorDefault, par_keys, par_vals, 2, NULL, NULL);
+ CVBufferSetAttachment(pb, kCVImageBufferPixelAspectRatioKey, par,
+ kCVAttachmentMode_ShouldPropagate);
+ CFRelease(par);
+ CFRelease(par_h);
+ CFRelease(par_v);
+}
+
+static CVPixelBufferRef vcc_pb_wrap_bgra(const vcc_frame_desc_t *frame) {
+ size_t len = (size_t)frame->bytes_per_row * frame->height;
+ uint8_t *copy = malloc(len);
+ if (!copy) return NULL;
+ memcpy(copy, frame->pixels, len);
+ CVPixelBufferRef pb = NULL;
+ CVReturn cvr = CVPixelBufferCreateWithBytes(
+ kCFAllocatorDefault, frame->width, frame->height, VCC_FMT_BGRA, copy,
+ frame->bytes_per_row, vcc_release_malloc_bytes, NULL, NULL, &pb);
+ if (cvr != kCVReturnSuccess || !pb) {
+ free(copy);
+ return NULL;
+ }
+ vcc_attach_camera_metadata(pb, 0);
+ return pb;
+}
+
+static CVPixelBufferRef vcc_pb_build_420v(const vcc_frame_desc_t *frame) {
+ CVPixelBufferRef pb = NULL;
+ CVReturn cvr = CVPixelBufferCreate(kCFAllocatorDefault, frame->width,
+ frame->height, VCC_FMT_420V, NULL, &pb);
+ if (cvr != kCVReturnSuccess || !pb) return NULL;
+
+ cvr = CVPixelBufferLockBaseAddress(pb, 0);
+ if (cvr != kCVReturnSuccess) {
+ CVPixelBufferRelease(pb);
+ return NULL;
+ }
+ uint8_t *y_base = CVPixelBufferGetBaseAddressOfPlane(pb, 0);
+ uint8_t *c_base = CVPixelBufferGetBaseAddressOfPlane(pb, 1);
+ size_t y_bpr = CVPixelBufferGetBytesPerRowOfPlane(pb, 0);
+ size_t c_bpr = CVPixelBufferGetBytesPerRowOfPlane(pb, 1);
+ if (!y_base || !c_base) {
+ CVPixelBufferUnlockBaseAddress(pb, 0);
+ CVPixelBufferRelease(pb);
+ return NULL;
+ }
+
+ if (vcc_is_planar_yuv(frame->pixel_format)) {
+ // 420v wire data → plane copy (Y then CbCr, per-frame strides).
+ uint32_t bpr1 = frame->bytes_per_row1 ? frame->bytes_per_row1
+ : 2u * (frame->width / 2);
+ const uint8_t *src_c = frame->pixels +
+ (size_t)frame->bytes_per_row * frame->height;
+ for (uint32_t y = 0; y < frame->height; y++) {
+ memcpy(y_base + y * y_bpr, frame->pixels + (size_t)y * frame->bytes_per_row,
+ frame->width);
+ }
+ for (uint32_t y = 0; y < frame->height / 2; y++) {
+ memcpy(c_base + y * c_bpr, src_c + (size_t)y * bpr1, 2u * (frame->width / 2));
+ }
+ } else {
+ vcc_bgra_to_420v(frame->pixels, frame->bytes_per_row, frame->width,
+ frame->height, y_base, (uint32_t)y_bpr, c_base,
+ (uint32_t)c_bpr);
+ }
+ CVPixelBufferUnlockBaseAddress(pb, 0);
+ vcc_attach_camera_metadata(pb, 1);
+ return pb;
+}
+
+CVPixelBufferRef vcc_pixel_buffer_from_frame(const vcc_frame_desc_t *frame,
+ uint32_t fmt_out) {
+ if (!frame || !frame->pixels || !frame->width || !frame->height ||
+ !frame->bytes_per_row) {
+ return NULL;
+ }
+ if (fmt_out == VCC_FMT_420V) return vcc_pb_build_420v(frame);
+ if (fmt_out == VCC_FMT_BGRA) {
+ if (frame->pixel_format == VCC_FMT_BGRA) return vcc_pb_wrap_bgra(frame);
+ // 420v wire → BGRA via tight intermediate.
+ uint32_t tight_bpr = frame->width * 4;
+ uint8_t *tight = malloc((size_t)tight_bpr * frame->height);
+ if (!tight) return NULL;
+ uint32_t bpr1 =
+ frame->bytes_per_row1 ? frame->bytes_per_row1 : 2u * (frame->width / 2);
+ vcc_420v_to_bgra(frame->pixels, frame->bytes_per_row,
+ frame->pixels + (size_t)frame->bytes_per_row * frame->height,
+ bpr1, frame->width, frame->height, tight, tight_bpr);
+ vcc_frame_desc_t tight_desc = *frame;
+ tight_desc.pixel_format = VCC_FMT_BGRA;
+ tight_desc.bytes_per_row = tight_bpr;
+ tight_desc.pixels = tight;
+ CVPixelBufferRef pb = vcc_pb_wrap_bgra(&tight_desc);
+ free(tight);
+ return pb;
+ }
+ return NULL;
+}
+
+int vcc_bgra_bytes_from_frame(const vcc_frame_desc_t *frame,
+ uint8_t **out_bytes, uint32_t *out_bpr) {
+ if (!frame || !out_bytes || !out_bpr) return -1;
+ uint32_t bpr = frame->width * 4;
+ uint8_t *buf = malloc((size_t)bpr * frame->height);
+ if (!buf) return -1;
+
+ if (frame->pixel_format == VCC_FMT_BGRA) {
+ for (uint32_t y = 0; y < frame->height; y++) {
+ memcpy(buf + (size_t)y * bpr, frame->pixels + (size_t)y * frame->bytes_per_row,
+ bpr);
+ }
+ } else if (vcc_is_planar_yuv(frame->pixel_format)) {
+ uint32_t bpr1 =
+ frame->bytes_per_row1 ? frame->bytes_per_row1 : 2u * (frame->width / 2);
+ vcc_420v_to_bgra(frame->pixels, frame->bytes_per_row,
+ frame->pixels + (size_t)frame->bytes_per_row * frame->height,
+ bpr1, frame->width, frame->height, buf, bpr);
+ } else {
+ free(buf);
+ return -1;
+ }
+ *out_bytes = buf;
+ *out_bpr = bpr;
+ return 0;
+}
+
+CGImageRef vcc_cgimage_from_pixel_buffer(CVPixelBufferRef pb) {
+ if (!pb) return NULL;
+ OSType fmt = CVPixelBufferGetPixelFormatType(pb);
+ size_t w = CVPixelBufferGetWidth(pb);
+ size_t h = CVPixelBufferGetHeight(pb);
+ if (!w || !h) return NULL;
+
+ if (fmt == VCC_FMT_BGRA) {
+ if (CVPixelBufferLockBaseAddress(pb, kCVPixelBufferLock_ReadOnly) !=
+ kCVReturnSuccess) {
+ return NULL;
+ }
+ const void *base = CVPixelBufferGetBaseAddress(pb);
+ size_t bpr = CVPixelBufferGetBytesPerRow(pb);
+ CGImageRef img = NULL;
+ if (base) {
+ CGColorSpaceRef cs = CGColorSpaceCreateDeviceRGB();
+ CGDataProviderRef dp = CGDataProviderCreateWithData(
+ NULL, base, bpr * h, NULL); // borrowed; unlocked below
+ img = CGImageCreate(w, h, 8, 32, bpr, cs,
+ kCGImageAlphaPremultipliedFirst |
+ kCGBitmapByteOrder32Little,
+ dp, NULL, false, kCGRenderingIntentDefault);
+ if (dp) CGDataProviderRelease(dp);
+ CGColorSpaceRelease(cs);
+ }
+ CVPixelBufferUnlockBaseAddress(pb, kCVPixelBufferLock_ReadOnly);
+ return img;
+ }
+
+ // 4:2:0 → BGRA → CGImage (copies; chroma decode is not cheap enough to
+ // borrow buffer memory for).
+ if (CVPixelBufferLockBaseAddress(pb, kCVPixelBufferLock_ReadOnly) !=
+ kCVReturnSuccess) {
+ return NULL;
+ }
+ vcc_frame_desc_t frame;
+ memset(&frame, 0, sizeof(frame));
+ frame.width = (uint32_t)w;
+ frame.height = (uint32_t)h;
+ frame.bytes_per_row = (uint32_t)CVPixelBufferGetBytesPerRowOfPlane(pb, 0);
+ frame.bytes_per_row1 =
+ (uint32_t)CVPixelBufferGetBytesPerRowOfPlane(pb, 1);
+ frame.pixel_format = (uint32_t)fmt;
+ frame.pixels = CVPixelBufferGetBaseAddressOfPlane(pb, 0);
+ frame.pixels_length = (size_t)frame.bytes_per_row * h;
+
+ uint8_t *bgra = NULL;
+ uint32_t bpr = 0;
+ int rc = frame.pixels ? vcc_bgra_bytes_from_frame(&frame, &bgra, &bpr) : -1;
+ CVPixelBufferUnlockBaseAddress(pb, kCVPixelBufferLock_ReadOnly);
+ if (rc != 0 || !bgra) return NULL;
+
+ size_t len = (size_t)bpr * h;
+ CGColorSpaceRef cs = CGColorSpaceCreateDeviceRGB();
+ CGDataProviderRef dp =
+ CGDataProviderCreateWithData(bgra, bgra, len, vcc_cg_release_data);
+ CGImageRef img = CGImageCreate(w, h, 8, 32, bpr, cs,
+ kCGImageAlphaPremultipliedFirst |
+ kCGBitmapByteOrder32Little,
+ dp, NULL, false, kCGRenderingIntentDefault);
+ if (dp) CGDataProviderRelease(dp); // owns bgra
+ else free(bgra);
+ CGColorSpaceRelease(cs);
+ return img;
+}
+
+// MARK: - format description
+
+OSStatus vcc_format_description_create_for_pb(
+ CVPixelBufferRef pb, CMVideoFormatDescriptionRef *out_desc) {
+ if (!pb || !out_desc) return VCC_PARAM_ERR;
+ // Inherits the pixel buffer's camera attachments (colorimetry, clean
+ // aperture, pixel aspect) as extensions and stays buffer-matched, which
+ // hand-built extension dictionaries cannot be (CoreMedia rejects them in
+ // CMVideoFormatDescriptionMatchesImageBuffer with -12743).
+ return CMVideoFormatDescriptionCreateForImageBuffer(kCFAllocatorDefault, pb,
+ out_desc);
+}
+
+// MARK: - sample buffer
+
+CMSampleBufferRef vcc_cmsb_create(CVPixelBufferRef pb,
+ CMVideoFormatDescriptionRef desc,
+ CMTime pts, CMTime dur,
+ uint32_t w, uint32_t h) {
+ if (!pb || !desc) return NULL;
+
+ CMSampleTimingInfo timing = {
+ .duration = dur,
+ .presentationTimeStamp = pts,
+ .decodeTimeStamp = kCMTimeInvalid,
+ };
+ CMSampleBufferRef cmsb = NULL;
+ OSStatus s = CMSampleBufferCreateForImageBuffer(
+ kCFAllocatorDefault, pb, true, NULL, NULL, desc, &timing, &cmsb);
+ if (s != noErr || !cmsb) {
+ fprintf(stderr, "vcam_dataplane: CMSampleBufferCreateForImageBuffer "
+ "failed: %d\n", (int)s);
+ return NULL;
+ }
+
+ // Camera intrinsic matrix, column-major matrix_float3x3 per the
+ // CMSampleBuffer.h contract:
+ // column 0 = (fx, 0, 0), column 1 = (0, fy, 0), column 2 = (ox, oy, 1)
+ // fx = fy = (w/2) / tan(HFOV/2) — square pixels, principal point at the
+ // frame center (no crop/offset between sensor and delivered buffer).
+ double fx = (0.5 * (double)w) / tan(VCC_VCAM_HFOV_DEG * M_PI / 360.0);
+ float m[9] = {
+ (float)fx, 0.0f, 0.0f,
+ 0.0f, (float)fx, 0.0f,
+ (float)w / 2.0f, (float)h / 2.0f, 1.0f,
+ };
+ CFDataRef intr = CFDataCreate(kCFAllocatorDefault, (const UInt8 *)m, sizeof(m));
+ CMSetAttachment(cmsb, kCMSampleBufferAttachmentKey_CameraIntrinsicMatrix,
+ intr, kCMAttachmentMode_ShouldNotPropagate);
+ CFRelease(intr);
+
+ // Landscape-native frames: orientation 1 ("up") — the buffer really does
+ // contain what it says, no rotation between sensor and consumer.
+ int32_t orientation = 1;
+ CFNumberRef orient_num =
+ CFNumberCreate(kCFAllocatorDefault, kCFNumberSInt32Type, &orientation);
+ CMSetAttachment(cmsb, vcc_orientation_key(), orient_num,
+ kCMAttachmentMode_ShouldNotPropagate);
+ CFRelease(orient_num);
+
+ // Every frame is a self-contained I-frame — muxers and PhotoOutput
+ // pipelines consult this.
+ CMSetAttachment(cmsb, kCMSampleAttachmentKey_DependsOnOthers,
+ kCFBooleanFalse, kCMAttachmentMode_ShouldPropagate);
+
+ return cmsb;
+}
+
+CMSampleBufferRef vcc_cmsb_from_frame(const vcc_frame_desc_t *frame,
+ uint32_t fmt_out,
+ vcc_timing_state_t *timing) {
+ if (!frame || !frame->pixels || !timing) return NULL;
+ if (fmt_out != VCC_FMT_BGRA && fmt_out != VCC_FMT_420V) return NULL;
+
+ CVPixelBufferRef pb = vcc_pixel_buffer_from_frame(frame, fmt_out);
+ if (!pb) return NULL;
+
+ CMVideoFormatDescriptionRef desc = NULL;
+ OSStatus s =
+ vcc_format_description_create_for_pb(pb, &desc);
+ if (s != noErr || !desc) {
+ CVPixelBufferRelease(pb);
+ return NULL;
+ }
+
+ CMTime pts, dur;
+ vcc_timing_advance(timing, frame->timestamp_ns, &pts, &dur);
+
+ CMSampleBufferRef cmsb =
+ vcc_cmsb_create(pb, desc, pts, dur, frame->width, frame->height);
+ CFRelease(desc);
+ CVPixelBufferRelease(pb);
+ if (!cmsb) return NULL;
+
+ // Provenance (diagnostics only; harmless for consumers).
+ CFStringRef provenance =
+ CFStringCreateWithFormat(kCFAllocatorDefault, NULL, CFSTR("%llu"),
+ (unsigned long long)frame->frame_index);
+ CMSetAttachment(cmsb, CFSTR("vphone.host_frame_index"), provenance,
+ kCMAttachmentMode_ShouldNotPropagate);
+ CFRelease(provenance);
+ return cmsb;
+}
diff --git a/VPhoneGuestComponents/VCamDataPlane/vcam_dataplane.h b/VPhoneGuestComponents/VCamDataPlane/vcam_dataplane.h
new file mode 100644
index 00000000..bbacb880
--- /dev/null
+++ b/VPhoneGuestComponents/VCamDataPlane/vcam_dataplane.h
@@ -0,0 +1,171 @@
+/*
+ * vcam_dataplane — shared CoreMedia data plane for the vphone virtual
+ * camera. One implementation used by BOTH guest dylibs (libvcamcaptured
+ * inside cameracaptured, libcamfix inside AVFoundation clients) and by
+ * the host-side macOS test harness (Tests/VCamDataPlaneTests.c).
+ *
+ * The shared-memory frame is the single source of truth. Everything a
+ * CoreMedia consumer can observe is derived from it:
+ *
+ * ┌── CVPixelBuffer (advertised pixel format)
+ * shm frame ──────┼── CMVideoFormatDescription (codec 4cc == pixels,
+ * │ clean aperture, pixel aspect, BT.709 colorimetry)
+ * ├── CMSampleBuffer (host-frame timing, camera intrinsic
+ * │ matrix, orientation, I-frame provenance)
+ * └── RGB derivations (CGImage / JPEG / IOSurface)
+ *
+ * Pure C + CoreMedia/CoreVideo, no Foundation — compiles for iOS guest
+ * (arm64e) and macOS host from the same source.
+ */
+
+#ifndef VCAM_DATAPLANE_H
+#define VCAM_DATAPLANE_H
+
+#include <CoreFoundation/CoreFoundation.h>
+#include <CoreGraphics/CoreGraphics.h>
+#include <CoreMedia/CoreMedia.h>
+#include <CoreVideo/CoreVideo.h>
+#include <stdint.h>
+
+// MARK: - constants
+
+#define VCC_FMT_BGRA 0x42475241u // 'BGRA' — 8-bit BGRA, 4 bytes/px
+#define VCC_FMT_420V 0x34323076u // '420v' — 8-bit 4:2:0, video range
+#define VCC_FMT_420F 0x34323066u // '420f' — 8-bit 4:2:0, full range
+
+/*
+ * Nominal horizontal field of view in degrees. Calibration knob: this one
+ * constant drives BOTH the intrinsic matrix focal length attached to every
+ * sample buffer AND the VideoFieldOfView key published on the
+ * FigCaptureSourceVideoFormat, so the device story and the per-frame story
+ * cannot drift apart. Calibrate against a physical device (capture + diff,
+ * see the research doc) rather than trusting this default.
+ */
+#define VCC_VCAM_HFOV_DEG 63.0
+
+/*
+ * Colorimetry we produce for 4:2:0 output: BT.709 primaries / transfer /
+ * matrix, video range (studio swing, Y [16,235], C [16,240]). Everything
+ * tagged on the pixel buffer and format description matches what the
+ * converter actually produces — no lies between tag and bits.
+ */
+#define VCC_VCAM_FRAMERATE_DEFAULT 30.0
+
+// MARK: - frame descriptor (the shm frame, deserialized)
+
+typedef struct {
+ uint32_t width;
+ uint32_t height;
+ uint32_t bytes_per_row; // plane-0 stride
+ uint32_t bytes_per_row1; // plane-1 stride (420v in); 0 → 2*(width/2)
+ uint32_t pixel_format; // VCC_FMT_* fourcc of `pixels`
+ uint64_t timestamp_ns; // host wall-clock ns for this frame
+ uint64_t frame_index; // host frame counter
+ const uint8_t *pixels; // plane 0 followed by plane 1 (planar formats)
+ size_t pixels_length;
+} vcc_frame_desc_t;
+
+// MARK: - timing
+
+/*
+ * Converts host frame timestamps into a monotonic guest PTS timeline with
+ * realistic per-frame durations. Host epoch-ns values are remapped to a
+ * stream-local 0-based timeline (CMTime values must stay well below 2^53
+ * for downstream float conversions to be lossless). Durations come from
+ * the observed inter-frame delta and fall back to the nominal 30 fps when
+ * deltas are implausible (bursts, stalls, duplicate ticks).
+ */
+typedef struct {
+ int have_last;
+ uint64_t anchor_ns;
+ uint64_t last_host_ns;
+ uint64_t last_pts_ns;
+ uint64_t last_dur_ns;
+} vcc_timing_state_t;
+
+void vcc_timing_init(vcc_timing_state_t *st);
+
+// Strictly-increasing by construction; safe to call from one thread only.
+void vcc_timing_advance(vcc_timing_state_t *st, uint64_t host_ts_ns,
+ CMTime *out_pts, CMTime *out_dur);
+
+// MARK: - pixel buffers
+
+// Returns 1 for 4:2:0 planar formats we know how to produce/consume.
+int vcc_is_planar_yuv(uint32_t fourcc);
+
+/*
+ * Build a CVPixelBuffer in `fmt_out` from the frame. Handles
+ * BGRA → BGRA (row-stride copy)
+ * BGRA → 420v (BT.709 video-range conversion, 2x2 chroma averaging)
+ * 420v → 420v (plane copy)
+ * 420v → BGRA (BT.709 video-range inverse)
+ * The returned buffer carries the camera image-buffer attachments:
+ * BT.709 YCbCr matrix (420v only) / primaries / transfer, clean aperture
+ * (full frame), pixel aspect 1:1. Caller releases. Returns NULL on failure.
+ */
+CVPixelBufferRef vcc_pixel_buffer_from_frame(const vcc_frame_desc_t *frame,
+ uint32_t fmt_out);
+
+/*
+ * Decode the frame to tightly-packed 8-bit BGRA (w*4 bytes per row, no
+ * padding) for RGB consumers (CGImage, JPEG, IOSurface staging). Caller
+ * frees *out_bytes. Accepts BGRA and 420v input frames.
+ */
+int vcc_bgra_bytes_from_frame(const vcc_frame_desc_t *frame,
+ uint8_t **out_bytes, uint32_t *out_bpr);
+
+/*
+ * One pixel buffer -> CGImage path for every RGB consumer (preview pump,
+ * photo tagging). Handles BGRA (zero-copy provider over the locked base)
+ * and 420v (converts via the BT.709 inverse). Returns a retained CGImage
+ * or NULL.
+ */
+CGImageRef vcc_cgimage_from_pixel_buffer(CVPixelBufferRef pb);
+
+// MARK: - format description
+
+/*
+ * CMVideoFormatDescription for the pixel buffer, carrying the same camera
+ * story as the bits. Mechanism (verified against CoreMedia on macOS):
+ * - the pixel buffer's camera attachments (YCbCr matrix, primaries,
+ * transfer, clean aperture, pixel aspect) are folded into the
+ * description's extensions by CMVideoFormatDescriptionCreateForImageBuffer
+ * - the description still passes CMVideoFormatDescriptionMatchesImageBuffer
+ * (hand-built extension dictionaries do NOT — CoreMedia rejects any
+ * extension set that isn't the buffer-derived spec)
+ * This replaces the naked CreateForImageBuffer shortcut the PR used, which
+ * produced an extension-less description that carried no camera metadata.
+ */
+OSStatus vcc_format_description_create_for_pb(
+ CVPixelBufferRef pb, CMVideoFormatDescriptionRef *out_desc);
+
+// MARK: - sample buffer
+
+/*
+ * Wrap `pb` + `desc` in a CMSampleBuffer with the camera metadata layer:
+ * - timing (pts + duration, from vcc_timing_advance)
+ * - kCMSampleBufferAttachmentKey_CameraIntrinsicMatrix (CFData,
+ * column-major matrix_float3x3, focal length derived from
+ * VCC_VCAM_HFOV_DEG and the frame dimensions)
+ * - kCGImagePropertyOrientation ("1" — landscape-native frames, exactly
+ * what the buffer contains)
+ * - kCMSampleAttachmentKey_DependsOnOthers = false (each frame is a
+ * self-contained I-frame, like real camera output)
+ * Returns a retained buffer or NULL.
+ */
+CMSampleBufferRef vcc_cmsb_create(CVPixelBufferRef pb,
+ CMVideoFormatDescriptionRef desc,
+ CMTime pts, CMTime dur,
+ uint32_t w, uint32_t h);
+
+/*
+ * Full chain: frame → pixel buffer (fmt_out) → format description →
+ * sample buffer with metadata. This is the one call both dylibs use.
+ * `timing` advances only on success. Returns a retained buffer or NULL.
+ */
+CMSampleBufferRef vcc_cmsb_from_frame(const vcc_frame_desc_t *frame,
+ uint32_t fmt_out,
+ vcc_timing_state_t *timing);
+
+#endif /* VCAM_DATAPLANE_H */