From 4992ed79947f3d539b692a6d57b0fb785284ff7c Mon Sep 17 00:00:00 2001 From: harry Date: Sat, 31 Oct 2026 10:06:21 +0900 Subject: [PATCH] chore(release): 0.17.0 The C and Rust APIs readied to stay compatible from 1.0 on (#152): the C API's structs carry their size and its planes their capacity, with new statuses and versions to compare (D69, #153); the Rust API's enums and structs can grow without breaking callers (D70, #154). Both break once here for it. The header's version constants move with the crate's, as the build requires; the README's roadmap, in both languages, the status line and the Swift package example name this release. Claude-Session: https://claude.ai/code/session_019fJGoCTvP5e7n599q3ZQ42 --- ARCHITECTURE.md | 2 +- CHANGELOG.md | 4 +++- Cargo.lock | 8 ++++---- Cargo.toml | 4 ++-- README.ko.md | 2 +- README.md | 2 +- crates/emberwave-ffi/README.md | 2 +- crates/emberwave-ffi/include/emberwave.h | 4 ++-- crates/emberwave-ffi/src/lib.rs | 4 ++-- 9 files changed, 17 insertions(+), 15 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index c54c42b..d0fc53f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -1,6 +1,6 @@ # Architecture -> **Status (v0.16.0).** The bitstream format is documented below and implemented by `emberwave_core::bitstream`, with a slow CPU reference decoder in `emberwave_core::cpu`, the wgpu/WGSL decoder in `emberwave_core::gpu` and the colour conversion in `emberwave_core::color`. The encoder runs on the CPU (`emberwave_core::encode`) and on the GPU (`emberwave_core::gpu`). `emberwave-cli` decodes and encodes files with them, `emberwave-web` plays them in a browser, also packet by packet as a stream arrives, and `emberwave-ffi` offers the decoder and the GPU encoder to C, also as an XCFramework for iPhone, iPad and Mac apps, and hands Metal clients the decoded picture in a texture, or its planes in three, also into the client's own textures and on its own queue without waiting, where calls take turns at its command buffers; it runs on a client's own Vulkan device and images as well, shares textures and fences with Direct3D 12 and 11 devices on Windows, and encodes a host's pictures straight from its textures, in RGB as captures hold them too; on Metal the planes are stored straight into the textures, and on Apple silicon the frames are written where the shaders read them. A decoder can keep the last frame's detail in the blocks a frame drawn in part lacks, where the picture is still. Decode and encode times are in `BENCHMARKS.md`. The decision log at the end is kept up to date. +> **Status (v0.17.0).** The bitstream format is documented below and implemented by `emberwave_core::bitstream`, with a slow CPU reference decoder in `emberwave_core::cpu`, the wgpu/WGSL decoder in `emberwave_core::gpu` and the colour conversion in `emberwave_core::color`. The encoder runs on the CPU (`emberwave_core::encode`) and on the GPU (`emberwave_core::gpu`). `emberwave-cli` decodes and encodes files with them, `emberwave-web` plays them in a browser, also packet by packet as a stream arrives, and `emberwave-ffi` offers the decoder and the GPU encoder to C, also as an XCFramework for iPhone, iPad and Mac apps, and hands Metal clients the decoded picture in a texture, or its planes in three, also into the client's own textures and on its own queue without waiting, where calls take turns at its command buffers; it runs on a client's own Vulkan device and images as well, shares textures and fences with Direct3D 12 and 11 devices on Windows, and encodes a host's pictures straight from its textures, in RGB as captures hold them too; on Metal the planes are stored straight into the textures, and on Apple silicon the frames are written where the shaders read them. A decoder can keep the last frame's detail in the blocks a frame drawn in part lacks, where the picture is still. Decode and encode times are in `BENCHMARKS.md`. The decision log at the end is kept up to date. ## Overview diff --git a/CHANGELOG.md b/CHANGELOG.md index e074ded..328d5e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,9 @@ All notable changes to emberwave. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/). -## [Unreleased] +## [0.17.0] - 2026-10-31 + +The C and Rust APIs, readied to stay compatible from 1.0 on, and broken once here for that. The C API's structs carry their size, so that a later version can add a member without breaking programs; its planes carry their capacity, which the calls check; it has statuses for a call the system lacks and for a buffer too small, and versions to compare the header with the library. The Rust API's enums and structs can grow without breaking callers. The changes below say what each caller changes. ### Added diff --git a/Cargo.lock b/Cargo.lock index c42c018..bc0eee1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -288,7 +288,7 @@ dependencies = [ [[package]] name = "emberwave-cli" -version = "0.16.0" +version = "0.17.0" dependencies = [ "clap", "emberwave-core", @@ -299,7 +299,7 @@ dependencies = [ [[package]] name = "emberwave-core" -version = "0.16.0" +version = "0.17.0" dependencies = [ "bytemuck", "naga", @@ -311,7 +311,7 @@ dependencies = [ [[package]] name = "emberwave-ffi" -version = "0.16.0" +version = "0.17.0" dependencies = [ "ash", "cbindgen", @@ -325,7 +325,7 @@ dependencies = [ [[package]] name = "emberwave-web" -version = "0.16.0" +version = "0.17.0" dependencies = [ "emberwave-core", "wasm-bindgen", diff --git a/Cargo.toml b/Cargo.toml index b035e57..f3e49e3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,7 +8,7 @@ members = [ ] [workspace.package] -version = "0.16.0" +version = "0.17.0" edition = "2024" license = "MIT" repository = "https://github.com/with-developer/emberwave" @@ -17,7 +17,7 @@ rust-version = "1.87" publish = false [workspace.dependencies] -emberwave-core = { path = "crates/emberwave-core", version = "0.16.0" } +emberwave-core = { path = "crates/emberwave-core", version = "0.17.0" } thiserror = "2" proptest = "1" # Native backends only: GLES would need EGL and the browser backend is for the diff --git a/README.ko.md b/README.ko.md index 13923da..7a2f490 100644 --- a/README.ko.md +++ b/README.ko.md @@ -142,7 +142,7 @@ iPhone 17의 Safari에서는 [벤치마크 페이지](https://with-developer.git ## 로드맵 -첫 릴리스까지의 마일스톤 M0~M5([#1](https://github.com/with-developer/emberwave/issues/1)~[#6](https://github.com/with-developer/emberwave/issues/6))를 마쳤고, 그 뒤로 CPU·GPU 인코더([#14](https://github.com/with-developer/emberwave/issues/14)), 브라우저 플레이어와 벤치마크 페이지([#15](https://github.com/with-developer/emberwave/issues/15)), 클라이언트와 호스트를 위한 C API([#16](https://github.com/with-developer/emberwave/issues/16), [#42](https://github.com/with-developer/emberwave/issues/42)), Metal 텍스처를 포함해 GPU 메모리의 그림을 주고받는 기능([#27](https://github.com/with-developer/emberwave/issues/27), [#33](https://github.com/with-developer/emberwave/issues/33)), iPhone·iPad·Mac 앱용 XCFramework([#52](https://github.com/with-developer/emberwave/issues/52))를 만들었습니다. 0.12에서는 Apple GPU에서 프레임마다 하던 복사 두 가지를 없앴습니다. Metal에서는 평면을 텍스처에 바로 쓰고, Apple silicon에서는 프레임을 셰이더가 읽는 메모리에 바로 씁니다([#86](https://github.com/with-developer/emberwave/issues/86)). 0.13에서는 스트림을 도착하는 대로 디코딩합니다. 브라우저 플레이어가 스트림을 패킷 단위로 받고, 모든 프레임에 가장 거친 레벨의 블록을 빠짐없이 담아 패킷을 잃은 프레임도 일부를 디코딩할 수 있게 했습니다. 패킷을 잃은 프레임을 블록이 얼마나 모였을 때 그릴지는 클라이언트가 정합니다. 클라이언트의 Metal 큐를 여러 스레드가 함께 써도 멈추지 않도록, emberwave의 호출은 큐의 명령 버퍼를 차례대로 씁니다([#109](https://github.com/with-developer/emberwave/issues/109), [#116](https://github.com/with-developer/emberwave/issues/116), [#123](https://github.com/with-developer/emberwave/issues/123), [#126](https://github.com/with-developer/emberwave/issues/126)). 0.14에서는 모든 플랫폼에서 클라이언트·호스트와 GPU를 함께 씁니다. 호출자의 Vulkan 장치 위에서 컨텍스트를 만들어 그 이미지에 세마포어와 함께 디코딩하고, Windows에서는 Direct3D 12·11 장치와 텍스처·펜스를 NT 핸들로 공유합니다. 호스트의 인코더는 그림이 담긴 텍스처를 그대로 읽으며, NV12 배치도 받습니다. 릴리스마다 XCFramework를 Swift 패키지가 받는 형태의 압축 파일로도 올립니다([#115](https://github.com/with-developer/emberwave/issues/115), [#133](https://github.com/with-developer/emberwave/issues/133), [#137](https://github.com/with-developer/emberwave/issues/137)). 0.15에서는 호스트가 화면을 캡처한 그대로 RGB 그림을 인코딩합니다. 인코더가 Metal·Vulkan·Direct3D의 BGRA·RGBA 텍스처나 CPU 메모리에서 그림을 읽으면서 Y'CbCr로 바꾸며, 정수로 계산하므로 어느 GPU에서나 같은 바이트가 나옵니다([#142](https://github.com/with-developer/emberwave/pull/142)). 0.16에서는 패킷을 잃어도 멈춰 있는 화면의 세부가 남습니다. 일부만 받은 프레임에서 빠진 세부 블록을, 화면이 움직이지 않은 곳이면 직전 프레임의 것으로 채웁니다. 클라이언트가 켤 때만 동작합니다. 웨이블릿 변환의 GPU 시간도 5분의 1 줄었습니다([#129](https://github.com/with-developer/emberwave/issues/129), [#147](https://github.com/with-developer/emberwave/pull/147)). 릴리스별 변경 사항은 [`CHANGELOG.md`](CHANGELOG.md)에 있습니다. +첫 릴리스까지의 마일스톤 M0~M5([#1](https://github.com/with-developer/emberwave/issues/1)~[#6](https://github.com/with-developer/emberwave/issues/6))를 마쳤고, 그 뒤로 CPU·GPU 인코더([#14](https://github.com/with-developer/emberwave/issues/14)), 브라우저 플레이어와 벤치마크 페이지([#15](https://github.com/with-developer/emberwave/issues/15)), 클라이언트와 호스트를 위한 C API([#16](https://github.com/with-developer/emberwave/issues/16), [#42](https://github.com/with-developer/emberwave/issues/42)), Metal 텍스처를 포함해 GPU 메모리의 그림을 주고받는 기능([#27](https://github.com/with-developer/emberwave/issues/27), [#33](https://github.com/with-developer/emberwave/issues/33)), iPhone·iPad·Mac 앱용 XCFramework([#52](https://github.com/with-developer/emberwave/issues/52))를 만들었습니다. 0.12에서는 Apple GPU에서 프레임마다 하던 복사 두 가지를 없앴습니다. Metal에서는 평면을 텍스처에 바로 쓰고, Apple silicon에서는 프레임을 셰이더가 읽는 메모리에 바로 씁니다([#86](https://github.com/with-developer/emberwave/issues/86)). 0.13에서는 스트림을 도착하는 대로 디코딩합니다. 브라우저 플레이어가 스트림을 패킷 단위로 받고, 모든 프레임에 가장 거친 레벨의 블록을 빠짐없이 담아 패킷을 잃은 프레임도 일부를 디코딩할 수 있게 했습니다. 패킷을 잃은 프레임을 블록이 얼마나 모였을 때 그릴지는 클라이언트가 정합니다. 클라이언트의 Metal 큐를 여러 스레드가 함께 써도 멈추지 않도록, emberwave의 호출은 큐의 명령 버퍼를 차례대로 씁니다([#109](https://github.com/with-developer/emberwave/issues/109), [#116](https://github.com/with-developer/emberwave/issues/116), [#123](https://github.com/with-developer/emberwave/issues/123), [#126](https://github.com/with-developer/emberwave/issues/126)). 0.14에서는 모든 플랫폼에서 클라이언트·호스트와 GPU를 함께 씁니다. 호출자의 Vulkan 장치 위에서 컨텍스트를 만들어 그 이미지에 세마포어와 함께 디코딩하고, Windows에서는 Direct3D 12·11 장치와 텍스처·펜스를 NT 핸들로 공유합니다. 호스트의 인코더는 그림이 담긴 텍스처를 그대로 읽으며, NV12 배치도 받습니다. 릴리스마다 XCFramework를 Swift 패키지가 받는 형태의 압축 파일로도 올립니다([#115](https://github.com/with-developer/emberwave/issues/115), [#133](https://github.com/with-developer/emberwave/issues/133), [#137](https://github.com/with-developer/emberwave/issues/137)). 0.15에서는 호스트가 화면을 캡처한 그대로 RGB 그림을 인코딩합니다. 인코더가 Metal·Vulkan·Direct3D의 BGRA·RGBA 텍스처나 CPU 메모리에서 그림을 읽으면서 Y'CbCr로 바꾸며, 정수로 계산하므로 어느 GPU에서나 같은 바이트가 나옵니다([#142](https://github.com/with-developer/emberwave/pull/142)). 0.16에서는 패킷을 잃어도 멈춰 있는 화면의 세부가 남습니다. 일부만 받은 프레임에서 빠진 세부 블록을, 화면이 움직이지 않은 곳이면 직전 프레임의 것으로 채웁니다. 클라이언트가 켤 때만 동작합니다. 웨이블릿 변환의 GPU 시간도 5분의 1 줄었습니다([#129](https://github.com/with-developer/emberwave/issues/129), [#147](https://github.com/with-developer/emberwave/pull/147)). 0.17에서는 1.0에 대비해 API를 다듬었습니다. C API의 구조체가 자기 크기를 담고 있어 프로그램을 깨뜨리지 않고 멤버를 늘릴 수 있고, 평면은 용량을 함께 넘깁니다. Rust API의 열거형과 구조체도 호출하는 쪽을 깨뜨리지 않고 늘어날 수 있습니다([#152](https://github.com/with-developer/emberwave/issues/152)). 릴리스별 변경 사항은 [`CHANGELOG.md`](CHANGELOG.md)에 있습니다. 앞으로 할 일입니다. 준비되는 대로 각각 릴리스합니다. diff --git a/README.md b/README.md index 06ed4a8..be9264c 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ Out of scope: network transport, RTP and FEC. ## Roadmap -Done: the milestones to the first release, M0 to M5 ([#1](https://github.com/with-developer/emberwave/issues/1) to [#6](https://github.com/with-developer/emberwave/issues/6)); since then the encoder, on the CPU and on the GPU ([#14](https://github.com/with-developer/emberwave/issues/14)), the browser player and its benchmark page ([#15](https://github.com/with-developer/emberwave/issues/15)), the C API for clients and hosts ([#16](https://github.com/with-developer/emberwave/issues/16), [#42](https://github.com/with-developer/emberwave/issues/42)), pictures to and from GPU memory, Metal textures included ([#27](https://github.com/with-developer/emberwave/issues/27), [#33](https://github.com/with-developer/emberwave/issues/33)), and the XCFramework for iPhone, iPad and Mac apps ([#52](https://github.com/with-developer/emberwave/issues/52)). 0.12 took two copies out of a frame's work on Apple's GPUs: the planes are stored straight into textures on Metal, and on Apple silicon the frames are written where the shaders read them ([#86](https://github.com/with-developer/emberwave/issues/86)). 0.13 decodes streams as they arrive: the browser player takes a stream packet by packet, every frame carries the blocks that a decode in part needs, a client chooses how much of a frame it draws in part, and calls on a client's own Metal queue take turns at its command buffers ([#109](https://github.com/with-developer/emberwave/issues/109), [#116](https://github.com/with-developer/emberwave/issues/116), [#123](https://github.com/with-developer/emberwave/issues/123), [#126](https://github.com/with-developer/emberwave/issues/126)). 0.14 shares the GPU with clients and hosts on every platform: a context on the caller's own Vulkan device decodes into its images with semaphores, Direct3D 12 and 11 devices on Windows share textures and fences through NT handles, and a host's encoder reads its pictures straight from its textures, NV12's layout included. Each release also has the XCFramework in the archive a Swift package takes ([#115](https://github.com/with-developer/emberwave/issues/115), [#133](https://github.com/with-developer/emberwave/issues/133), [#137](https://github.com/with-developer/emberwave/issues/137)). 0.15 encodes pictures in RGB, as hosts' screen captures hold them: the encoder converts them to Y'CbCr as it reads them, from a BGRA or RGBA texture of Metal, Vulkan or Direct3D or from CPU memory, in integers that make the same bytes on every GPU ([#142](https://github.com/with-developer/emberwave/pull/142)). 0.16 keeps a still picture's detail through lost packets: where the picture has not moved, a frame drawn in part fills the blocks of detail it lacks with the last frame's, when a client asks for it. Its wavelet transforms also take a fifth less GPU time ([#129](https://github.com/with-developer/emberwave/issues/129), [#147](https://github.com/with-developer/emberwave/pull/147)). [`CHANGELOG.md`](CHANGELOG.md) has each release. +Done: the milestones to the first release, M0 to M5 ([#1](https://github.com/with-developer/emberwave/issues/1) to [#6](https://github.com/with-developer/emberwave/issues/6)); since then the encoder, on the CPU and on the GPU ([#14](https://github.com/with-developer/emberwave/issues/14)), the browser player and its benchmark page ([#15](https://github.com/with-developer/emberwave/issues/15)), the C API for clients and hosts ([#16](https://github.com/with-developer/emberwave/issues/16), [#42](https://github.com/with-developer/emberwave/issues/42)), pictures to and from GPU memory, Metal textures included ([#27](https://github.com/with-developer/emberwave/issues/27), [#33](https://github.com/with-developer/emberwave/issues/33)), and the XCFramework for iPhone, iPad and Mac apps ([#52](https://github.com/with-developer/emberwave/issues/52)). 0.12 took two copies out of a frame's work on Apple's GPUs: the planes are stored straight into textures on Metal, and on Apple silicon the frames are written where the shaders read them ([#86](https://github.com/with-developer/emberwave/issues/86)). 0.13 decodes streams as they arrive: the browser player takes a stream packet by packet, every frame carries the blocks that a decode in part needs, a client chooses how much of a frame it draws in part, and calls on a client's own Metal queue take turns at its command buffers ([#109](https://github.com/with-developer/emberwave/issues/109), [#116](https://github.com/with-developer/emberwave/issues/116), [#123](https://github.com/with-developer/emberwave/issues/123), [#126](https://github.com/with-developer/emberwave/issues/126)). 0.14 shares the GPU with clients and hosts on every platform: a context on the caller's own Vulkan device decodes into its images with semaphores, Direct3D 12 and 11 devices on Windows share textures and fences through NT handles, and a host's encoder reads its pictures straight from its textures, NV12's layout included. Each release also has the XCFramework in the archive a Swift package takes ([#115](https://github.com/with-developer/emberwave/issues/115), [#133](https://github.com/with-developer/emberwave/issues/133), [#137](https://github.com/with-developer/emberwave/issues/137)). 0.15 encodes pictures in RGB, as hosts' screen captures hold them: the encoder converts them to Y'CbCr as it reads them, from a BGRA or RGBA texture of Metal, Vulkan or Direct3D or from CPU memory, in integers that make the same bytes on every GPU ([#142](https://github.com/with-developer/emberwave/pull/142)). 0.16 keeps a still picture's detail through lost packets: where the picture has not moved, a frame drawn in part fills the blocks of detail it lacks with the last frame's, when a client asks for it. Its wavelet transforms also take a fifth less GPU time ([#129](https://github.com/with-developer/emberwave/issues/129), [#147](https://github.com/with-developer/emberwave/pull/147)). 0.17 readies the APIs for 1.0: the C API's structs carry their size, so that they can grow without breaking programs, its planes their capacity, and the Rust API's enums and structs can grow without breaking callers ([#152](https://github.com/with-developer/emberwave/issues/152)). [`CHANGELOG.md`](CHANGELOG.md) has each release. Next, each in a release when it is ready: diff --git a/crates/emberwave-ffi/README.md b/crates/emberwave-ffi/README.md index 015a0e8..8eb0f5f 100644 --- a/crates/emberwave-ffi/README.md +++ b/crates/emberwave-ffi/README.md @@ -81,7 +81,7 @@ A Swift package names the XCFramework as a binary target. From a release, it tak // In the app's Package.swift, with the version of the release: .binaryTarget( name: "Emberwave", - url: "https://github.com/with-developer/emberwave/releases/download/v0.16.0/Emberwave.xcframework.zip", + url: "https://github.com/with-developer/emberwave/releases/download/v0.17.0/Emberwave.xcframework.zip", checksum: "..." // the release's SHA256SUMS line for Emberwave.xcframework.zip ), .target( diff --git a/crates/emberwave-ffi/include/emberwave.h b/crates/emberwave-ffi/include/emberwave.h index 8820151..ff44332 100644 --- a/crates/emberwave-ffi/include/emberwave.h +++ b/crates/emberwave-ffi/include/emberwave.h @@ -45,7 +45,7 @@ #define EMBERWAVE_VERSION_MAJOR 0 // The minor version of emberwave that this header belongs to. -#define EMBERWAVE_VERSION_MINOR 16 +#define EMBERWAVE_VERSION_MINOR 17 // The patch version of emberwave that this header belongs to. #define EMBERWAVE_VERSION_PATCH 0 @@ -54,7 +54,7 @@ // minor times 100 plus patch: 1600 for 0.16.0. `emberwave_version_number()` // gives the library's, which differs when a program runs with another // library than the one it was built for. -#define EMBERWAVE_VERSION 1600 +#define EMBERWAVE_VERSION 1700 // 4:2:0: the chroma planes have half the width and height of the luma plane, // whose width and height are even. diff --git a/crates/emberwave-ffi/src/lib.rs b/crates/emberwave-ffi/src/lib.rs index c0e28a3..291daf8 100644 --- a/crates/emberwave-ffi/src/lib.rs +++ b/crates/emberwave-ffi/src/lib.rs @@ -92,14 +92,14 @@ pub enum EmberwaveStatus { /// The major version of emberwave that this header belongs to. pub const EMBERWAVE_VERSION_MAJOR: u32 = 0; /// The minor version of emberwave that this header belongs to. -pub const EMBERWAVE_VERSION_MINOR: u32 = 16; +pub const EMBERWAVE_VERSION_MINOR: u32 = 17; /// The patch version of emberwave that this header belongs to. pub const EMBERWAVE_VERSION_PATCH: u32 = 0; /// The version this header belongs to as one number, major times 10000 plus /// minor times 100 plus patch: 1600 for 0.16.0. `emberwave_version_number()` /// gives the library's, which differs when a program runs with another /// library than the one it was built for. -pub const EMBERWAVE_VERSION: u32 = 1600; +pub const EMBERWAVE_VERSION: u32 = 1700; /// The library's version as `EMBERWAVE_VERSION` numbers it, from the crate's. const VERSION_NUMBER: u32 = decimal(env!("CARGO_PKG_VERSION_MAJOR")) * 10000