-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
b0a6d07
commit 4581c6d
Showing
20 changed files
with
786 additions
and
530 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
name: Test Swift Package | ||
|
||
on: | ||
pull_request: | ||
branches: [main] | ||
|
||
jobs: | ||
test: | ||
runs-on: macos-latest | ||
|
||
steps: | ||
- uses: actions/checkout@v3 | ||
- uses: swift-actions/setup-swift@v2 | ||
with: | ||
swift-version: '5.9' | ||
|
||
- name: Build | ||
run: swift build | ||
|
||
- name: Run Tests | ||
run: swift test |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
version: 1 | ||
builder: | ||
configs: | ||
- documentation_targets: [CoreVideoTools] | ||
scheme: CoreVideoTools |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,56 +1,89 @@ | ||
# core-video-tools | ||
# CoreVideoTools | ||
|
||
A set of extensions and utilities to work with [CoreVideo](https://developer.apple.com/documentation/corevideo?language=objc) types. | ||
[![Platform Compatibility](https://img.shields.io/badge/Platforms-iOS%20|%20macOS-brightgreen)](https://swift.org/platforms/) | ||
[![Swift Version](https://img.shields.io/badge/Swift-5.9-orange)](https://swift.org) | ||
|
||
## CVPixelFormat | ||
<p align="left"> | ||
<img src="Sources/CoreVideoTools/CoreVideoTools.docc/Resources/table-of-contents-art/[email protected]", width="120"> | ||
</p> | ||
|
||
While debuging `Core Video` objects, you need to understand what pixel format is used in them. | ||
To do this using vanilla API you are forced to find a mathing `OSType` value, because `OSType` if basically a number. | ||
This project uses [`CVPixelFormat`](Sources/CoreVideoTools/CVPixelFormat.swift) enum istead of vanilla `OSType` public vars which is much more handy, and you can easyly get a `description` of a current pixel format. | ||
## Overview | ||
|
||
```swift | ||
let cvPixelFormat: CVPixelFormat = cvPixelBuffer.cvPixelFormat | ||
let description = cvPixelFormat.description | ||
``` | ||
CoreVideoTools offers a more idiomatic Swift interface to `CoreVideo` functionality, making it easier and safer to work with `CVPixelBuffers`, `IOSurfaces`, and related `CoreVideo` concepts in Swift code. | ||
|
||
Please see [the package's documentation](https://swiftpackageindex.com/computer-graphics-tools/core-video-tools/documentation/corevideotools) | ||
for more detailed usage instructions. | ||
|
||
## Swifty API | ||
## CVPixelBuffer | ||
|
||
There are a lot Swift wrappers over vanilla CVPixelBuffer C-style API: | ||
|
||
**Vanilla API:** | ||
**Swifty API:** | ||
|
||
```swift | ||
let width = CVPixelBufferGetWidth(cvPixelBuffer) | ||
let height = CVPixelBufferGetHeight(cvPixelBuffer) | ||
let width = pixelBuffer.width | ||
let height = pixelBuffer.height | ||
let format = pixelBuffer.cvPixelFormat | ||
let bytesPerRow = pixelBuffer.bytesPerRow | ||
``` | ||
|
||
// ... | ||
**Convenience Init:** | ||
|
||
let bytesPerElement = IOSurfaceGetBytesPerRow(ioSurface) | ||
let bytesPerRow = IOSurfaceGetBytesPerRow(ioSurface) | ||
```swift | ||
let pixelBuffer = try CVPixelBuffer.create( | ||
width: 1920, | ||
height: 1080, | ||
cvPixelFormat: .type_32BGRA | ||
) | ||
``` | ||
|
||
**Swifty API:** | ||
Check out more examples in the [Working With CVPixelBuffer](Sources/CoreVideoTools/CoreVideoTools.docc/WorkingWithCVPixelBuffer.md). | ||
|
||
## IOSurface | ||
|
||
**Convenience Init:** | ||
|
||
```swift | ||
let width = cvPixelBuffer.width | ||
let height = cvPixelBuffer.height | ||
let surface = try IOSurface.create( | ||
width: 1920, | ||
height: 1080, | ||
cvPixelFormat: .type_32BGRA, | ||
bytesPerElement: 4, | ||
bytesPerRow: 1920 * 4 | ||
) | ||
``` | ||
|
||
For more detail, please checkout [Working With IOSurface](Sources/CoreVideoTools/CoreVideoTools.docc/WorkingWithIOSurface.md). | ||
|
||
// ... | ||
## CVPixelFormat | ||
|
||
While debuging `Core Video` objects, you need to understand what pixel format is used in them. | ||
To do this using vanilla API you are forced to find a matching `OSType` value, because `OSType` if basically a number. | ||
This project uses [`CVPixelFormat`](Sources/CoreVideoTools/CVPixelFormat.swift) enum istead of vanilla `OSType` public vars which is much more handy, and you can easily get a `description` of a current pixel format. | ||
|
||
let bytesPerElement = ioSurface.bytesPerElement | ||
let bytesPerRow = ioSurface.bytesPerRow | ||
```swift | ||
let cvPixelFormat: CVPixelFormat = cvPixelBuffer.cvPixelFormat | ||
let description = cvPixelFormat.description | ||
``` | ||
|
||
## CVReturn Result & CVError | ||
|
||
There are some functions in Core Video that return a code which helps if the operation succeeded. | ||
There are some functions in Core Video that return a code which helps if the operation succeeded. | ||
This project aims to simplify this error checking. `CVReturn` [`Result`](Sources/CoreVideoTools/Extensions/CoreVideo/CVReturn/CVReturn+Result.swift) and [`CVError`](Sources/CoreVideoTools/CVError.swift) types are used to wrap vanilla API with thowable functions. | ||
|
||
**Vanilla API:** | ||
|
||
```swift | ||
let returnCode = CVPixelBufferLockBaseAddress(cvPixelBuffer, lockFlags) | ||
guard returnCode == kCVReturnSuccess else { // handle the error ... | ||
guard returnCode == kCVReturnSuccess else { /* handle the error ... */ } | ||
``` | ||
|
||
**Swifty API:** | ||
|
||
```swift | ||
try cvPixelBuffer.lockBaseAddress(lockFlags: lockFlags) | ||
``` | ||
|
||
## License | ||
|
||
MetalTools is licensed under [MIT license](LICENSE). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
39 changes: 39 additions & 0 deletions
39
Sources/CoreVideoTools/CoreVideoTools.docc/CoreVideoTools.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,39 @@ | ||
# ``CoreVideoTools`` | ||
|
||
![CoreVideoTools](core-video-tools.png) | ||
|
||
CoreVideo Tools offers a more idiomatic Swift interface to CoreVideo functionality, making it easier and safer to work with pixel buffers, IOSurfaces, and related CoreVideo concepts in Swift code. | ||
|
||
## Topics | ||
|
||
### Articles | ||
|
||
- <doc:WorkingWithCVPixelBuffer> | ||
- <doc:WorkingWithIOSurface> | ||
|
||
### CVPixelBuffer Extensions | ||
|
||
- ``CoreVideo/CVBuffer/width`` | ||
- ``CoreVideo/CVBuffer/height`` | ||
- ``CoreVideo/CVBuffer/cvPixelFormat`` | ||
- ``CoreVideo/CVBuffer/baseAddress`` | ||
- ``CoreVideo/CVBuffer/bytesPerRow`` | ||
- ``CoreVideo/CVBuffer/lockBaseAddress(lockFlags:)`` | ||
- ``CoreVideo/CVBuffer/unlockBaseAddress(unlockFlags:)`` | ||
- ``CoreVideo/CVBuffer/create(width:height:cvPixelFormat:attachments:allocator:)`` | ||
- ``CoreVideo/CVBuffer/blankCopy()`` | ||
- ``CoreVideo/CVBuffer/deepCopy()`` | ||
|
||
### IOSurface Extensions | ||
|
||
- ``IOSurface/IOSurface/CacheMode`` | ||
- ``IOSurface/IOSurface/create(width:height:cvPixelFormat:bytesPerElement:bytesPerRow:cacheMode:additionalProperties:)`` | ||
|
||
### Error Handling | ||
|
||
- ``CVError`` | ||
- ``Swift/Int32/Result`` | ||
|
||
### Pixel Formats | ||
|
||
- ``CVPixelFormat`` |
Binary file added
BIN
+412 KB
...ols/CoreVideoTools.docc/Resources/table-of-contents-art/[email protected]
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.