Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 11 additions & 26 deletions runtimes/apple/apple.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,6 @@ import { Apple } from "/snippets/constants.mdx"

<Demos examples={['dataBindingQuickStart']} runtime="apple" />

<Note>
A new runtime is available as part of the existing Apple runtime package. The new runtime is experimental and may be subject to breaking changes. The legacy runtime is still supported and will continue to be supported in the near future, but is now considered to be in maintenance mode. It is recommended to begin using the new API in new projects and provide feedback, and to investigate migrating existing projects to the new API when feasible.
</Note>

## Overview

This guide documents how to get started using the Apple runtime library. Rive runtime libraries are open-source. The source is available in its [GitHub repository](https://github.com/rive-app/rive-ios).
Expand Down Expand Up @@ -67,10 +63,10 @@ Follow the steps below for a quick start on integrating Rive into your Apple app
```
</Step>
<Step title="Import Rive">
The new API types are behind the `RiveExperimental` SPI, so the standard runtime import must be prefixed with `@_spi(RiveExperimental)`.
The new Apple runtime is available in the same Swift package and CocoaPods pod as the legacy runtime. Both runtime APIs are available in the same package, so you can import the runtime using the same import statement.

```swift
@_spi(RiveExperimental) import RiveRuntime
import RiveRuntime
```
</Step>
<Step title="Create a Worker">
Expand All @@ -81,8 +77,6 @@ Follow the steps below for a quick start on integrating Rive into your Apple app
```swift
// In an async context
let worker = try await Worker()
// In a sync context
let worker = try Worker()
```

For more information on threading, see [Threading](#threading).
Expand All @@ -97,24 +91,19 @@ Follow the steps below for a quick start on integrating Rive into your Apple app
<CodeGroup>
```swift Local File
let worker = try await Worker()
// In a sync context
let worker = try Worker()
let file = File(source: .local("my_file", Bundle.main), worker: worker)
let file = try await File(source: .local("my_file", Bundle.main), worker: worker)
```

```swift Remote URL
let worker = try await Worker()
// In a sync context
let worker = try Worker()
let file = File(source: .url(URL(string: "https://example.com/my_file.riv")!, worker: worker))
let url: URL = URL(string: "https://example.com/my_file.riv")!
let file = try await File(source: .url(url), worker: worker)
```

```swift Data
let worker = try await Worker()
// In a sync context
let worker = try Worker()
let data: Data = ...
let file = File(source: .data(data), worker: worker)
let file = try await File(source: .data(data), worker: worker)
```
</CodeGroup>
</Step>
Expand All @@ -127,9 +116,7 @@ Follow the steps below for a quick start on integrating Rive into your Apple app
```swift UIKit
let riveView = RiveUIView({
let worker = try await Worker()
// In a sync context
let worker = try Worker()
let file = File(source: .local("my_file", Bundle.main))
let file = try await File(source: .local("my_file", Bundle.main), worker: worker)
return try await Rive(file: file)
})
view.addSubview(riveView)
Expand All @@ -146,7 +133,7 @@ Follow the steps below for a quick start on integrating Rive into your Apple app
// After having created a `Rive` object, you can initialize your view.
AsyncRiveUIViewRepresentable {
let worker = try await Worker()
let file = File(source: .local("my_file", Bundle.main))
let file = try await File(source: .local("my_file", Bundle.main), worker: worker)
return try await Rive(file: file)
}
}
Expand Down Expand Up @@ -227,11 +214,11 @@ Follow the steps below for a quick start on integrating Rive into your Apple app
</CodeGroup>
</Step>
<Step title="Examples">
For basic usage, see the [Marty](https://github.com/rive-app/rive-ios/blob/main/Example-iOS/Source/Examples/Experimental/MartyView.swift) example in our Example app.
For basic usage, see the [Marty](https://github.com/rive-app/rive-ios/blob/main/Example-iOS/Source/Examples/Concurrency/MartyView.swift) example in our Example app.

For a more complete example, see the [Quick Start](https://github.com/rive-app/rive-ios/blob/main/Example-iOS/Source/Examples/Experimental/QuickStartView.swift) example in our Example app, which demonstrates how to use data binding.
For a more complete example, see the [Quick Start](https://github.com/rive-app/rive-ios/blob/main/Example-iOS/Source/Examples/Concurrency/QuickStartView.swift) example in our Example app, which demonstrates how to use data binding.

For examples on how to pause and resume animations, as well as set frame rate, see the [Player](https://github.com/rive-app/rive-ios/blob/main/Example-iOS/Source/Examples/Experimental/PlayerView.swift) example in our Example app.
For examples on how to pause and resume animations, as well as set frame rate, see the [Player](https://github.com/rive-app/rive-ios/blob/main/Example-iOS/Source/Examples/Concurrency/PlayerView.swift) example in our Example app.
</Step>
</Steps>
</Tab>
Expand Down Expand Up @@ -421,8 +408,6 @@ Follow the steps below for a quick start on integrating Rive into your Apple app
```swift
// In an async context
let worker = try await Worker()
// In a sync context
let worker = try Worker()
let file = try await File(source: ..., worker: worker)
```

Expand Down
2 changes: 1 addition & 1 deletion runtimes/apple/artboards.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ import { Apple } from "/snippets/constants.mdx"
Remember that the Rive configuration for a view is the `Rive` type. In the overview, we show initializing a `Rive` object with a file, opting to use the default artboard and state machine. However, you can initialize a `Rive` object with a specific artboard:
```swift
let worker = try await Worker()
let file = try await File(source: .local("my_file", Bundle.main))
let file = try await File(source: .local("my_file", Bundle.main), worker: worker)
let artboardByName = try await file.createArtboard("Artboard")
let rive = try await Rive(file: file, artboard: artboardByName)
```
Expand Down
3 changes: 2 additions & 1 deletion runtimes/apple/caching-a-rive-file.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ import Overview from "/snippets/runtimes/caching/overview.mdx"
}

// Load and cache the file once
let file = try await File(source: ..., worker: Worker())
let worker = try await Worker()
let file = try await File(source: ..., worker: worker)

// Create a builder with the cached file
let builder = RiveBuilder(file: file)
Expand Down
12 changes: 6 additions & 6 deletions runtimes/apple/data-binding.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -74,20 +74,20 @@ import { Apple } from "/snippets/constants.mdx"

// When using a view model by name:
// A blank view model instance
var blankInstance = try await file.createViewModelInstance(from: .blank(from: .name("ViewModel")))
var blankInstance = try await file.createViewModelInstance(.blank(from: .name("ViewModel")))
// The default instance for the view model
var defaultInstance = try await file.createViewModelInstance(from: .name("ViewModel"))
var defaultInstance = try await file.createViewModelInstance(.viewModelDefault(from: .name("ViewModel")))
// An instance by name from the view model
var namedInstance = try await file.createViewModelInstance(from: .name("Instance", from: .name("ViewModel")))
var namedInstance = try await file.createViewModelInstance(.name("Instance", from: .name("ViewModel")))

// Alternatively, using the default view model for an artboard
let artboard: Artboard = ...
// A blank view model instance
blankInstance = try await file.createViewModelInstance(from: .blank(from: .artboardDefault(Artboard)))
blankInstance = try await file.createViewModelInstance(.blank(from: .artboardDefault(Artboard)))
// The default instance for the view model
defaultInstance = try await file.createViewModelInstance(from: .viewModelDefault(from: .artboardDefault(Artboard)))
defaultInstance = try await file.createViewModelInstance(.viewModelDefault(from: .artboardDefault(Artboard)))
// An instance by name from the view model
namedInstance = try await file.createViewModelInstance(from: .name("Instance", from: .artboardDefault(Artboard)))
namedInstance = try await file.createViewModelInstance(.name("Instance", from: .artboardDefault(Artboard)))
```
</Tab>
<Tab title={Apple.legacyRuntimeName}>
Expand Down
8 changes: 5 additions & 3 deletions runtimes/apple/layouts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,12 @@ import ResponsiveLayouts from "/snippets/runtimes/layouts/responsive-layouts.mdx
<Tab title={Apple.currentRuntimeName}>
You can set the fit and layout options on a `Rive` object. The `.fit` can be updated at runtime without creating a new `Rive` object.

For all possible options, see [Fit.swift](https://github.com/rive-app/rive-ios/blob/main/Source/Experimental/View/Fit.swift)
For all possible options, see [Fit.swift](https://github.com/rive-app/rive-ios/blob/main/Source/Concurrency/View/Fit.swift)

```swift
// Set a fit and alignment for an artboard that does not use layouts
let file = try await File(source: ..., worker: Worker())
let worker = try await Worker()
let file = try await File(source: ..., worker: worker)
var rive = try await Rive(file: file, fit: .contain(alignment: .center))
// Update the fit and alignment at runtime
rive.fit = .fitWidth(alignment: .topCenter)
Expand Down Expand Up @@ -157,7 +158,8 @@ import ResponsiveLayouts from "/snippets/runtimes/layouts/responsive-layouts.mdx
When creating a new `Rive` object, you can set the fit to layout, with two options for the scale factor: automatic or explicit.

```swift
let file = try await File(source: ..., worker: Worker())
let worker = try await Worker()
let file = try await File(source: ..., worker: worker)
// Create a new Rive object with a layout fit that automatically determines the scale factor based on the screen the view is being displayed on
var rive = try await Rive(file: file, fit: .layout(scaleFactor: .automatic))
// Or, use an explicit scale factor
Expand Down
16 changes: 3 additions & 13 deletions runtimes/apple/migrating-from-legacy.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,22 +21,12 @@ This guide covers:

## Package and Import

The new Apple runtime is available in the same Swift package and CocoaPods pod as the legacy runtime.

The new Apple runtime APIs are currently behind the `@_spi(RiveExperimental)` SPI:

```swift
@_spi(RiveExperimental) import RiveRuntime
```

Compared to the legacy runtime:
The new Apple runtime is available in the same Swift package and CocoaPods pod as the legacy runtime. Both runtime APIs are available in the same package, so you can import the runtime using the same import statement.

```swift
import RiveRuntime
```

This is a temporary transition mechanism while the new API remains experimental.

## Asynchronous APIs

The new runtime is built around Swift Concurrency. Most setup and query operations are asynchronous and should be called from an async context.
Expand Down Expand Up @@ -482,7 +472,7 @@ The new runtime binds artboards with a typed property descriptor and `setValue`
```swift
let worker = try await WorkerProvider.shared.worker()
let file = try await File(source: .local("my_rive_file", Bundle.main), worker: worker)
let viewModelInstance = try await file.createViewModelInstance(from: .name("My View Model"))
let viewModelInstance = try await file.createViewModelInstance(.viewModelDefault(from: .name("My View Model")))

let artboardProperty = ArtboardProperty(path: "path/to/artboard")
let artboard = try await file.createArtboard("My Artboard")
Expand Down Expand Up @@ -574,7 +564,7 @@ In the new runtime, update the bound value after the view is created. No explici
let worker = try await WorkerProvider.shared.worker()
let file = try await File(source: .local("my_rive_file", Bundle.main), worker: worker)

let instance = try await file.createViewModelInstance(from: .name("My View Model"))
let instance = try await file.createViewModelInstance(.viewModelDefault(from: .name("My View Model")))
let property = StringProperty(path: "path/to/string")
let rive = try await Rive(file: file, dataBind: .instance(instance))
let riveView = RiveUIView(rive: rive)
Expand Down
2 changes: 1 addition & 1 deletion runtimes/apple/state-machines.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ import { Apple } from "/snippets/constants.mdx"

```swift
let worker = try await Worker()
let file = try await File(source: .local("my_file", Bundle.main))
let file = try await File(source: .local("my_file", Bundle.main), worker: worker)
let artboardByName = try await file.createArtboard("Artboard")
let stateMachine = try await artboardByName.createStateMachine("StateMachine")
let rive = try await Rive(file: file, artboard: artboardByName, stateMachine: stateMachine)
Expand Down
2 changes: 1 addition & 1 deletion snippets/constants.mdx
Original file line number Diff line number Diff line change
@@ -1 +1 @@
export const Apple = { currentRuntimeName: "New Runtime (Experimental)", legacyRuntimeName: "Legacy Runtime" };
export const Apple = { currentRuntimeName: "New Runtime", legacyRuntimeName: "Legacy Runtime" };