Lib PAG CMP

https://github.com/limuyang2/pag-cmp
Admin
Lib Pag Cmp is a Compose Multiplatform wrapper for Tencent libpag, providing a common PagView...
Tokens:58,113
Snippets:318
Trust Score:8.5
License:MIT
Update:17 hours ago
Show doc for...
Tokens:
Raw
### PagView Parameters

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Common parameters exposed by PagView on all supported platforms. These control playback, rendering, and caching behavior.

```APIDOC
## PagView Parameters

### Description
Common parameters exposed by PagView on all supported platforms. These control playback, rendering, and caching behavior.

### Parameters
- **isPlaying** (Boolean) - Optional - Starts or pauses playback.
- **progress** (Float) - Optional - Manual progress in 0.0..1.0. When set while paused, the current frame is flushed.
- **repeatCount** (Int) - Optional - Native libpag repeat count. 0 means infinite repeat.
- **scaleMode** (ScaleMode) - Optional - Controls how PAG content fits inside the render area.
- **cacheEnabled** (Boolean) - Optional - Enables libpag render cache.
- **videoEnabled** (Boolean) - Optional - Enables video sequence rendering when the PAG file contains video content.
- **useDiskCache** (Boolean) - Optional - Enables libpag disk cache on platforms that expose it.

### Notes
- `scaleMode` only affects the content transform inside the native PAG renderer. It does not measure, resize, or otherwise affect the Compose `PagView` layout bounds.
```

--------------------------------

### Build Verification Commands

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Run these Gradle commands to compile the library for each target platform. Each command verifies compilation for a specific Kotlin target: Android, iOS (arm64 and simulator), JVM, JS, and WasmJS.

```shell
./gradlew :lib-pag-cmp:compileAndroidMain
```

```shell
./gradlew :lib-pag-cmp:compileKotlinIosArm64
```

```shell
./gradlew :lib-pag-cmp:compileKotlinIosSimulatorArm64
```

```shell
./gradlew :lib-pag-cmp:compileKotlinJvm
```

```shell
./gradlew :lib-pag-cmp:compileKotlinJs
```

```shell
./gradlew :lib-pag-cmp:compileKotlinWasmJs
```

--------------------------------

### Load PAG from resource URI with Res.getUri

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

For .pag files in src/commonMain/composeResources/files/, pass the URI returned by Res.getUri("files/name.pag") to PagView(path). Do not pass the raw resource-relative path.

```kotlin
@Composable
fun ResourcePathAnimation() {
    PagView(
        path = Res.getUri("files/loading_bmp.pag"),
        modifier = Modifier.size(160.dp),
        scaleMode = PagScaleMode.LetterBox,
    )
}
```

--------------------------------

### Load PAG from path (file, URI, or URL)

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Pass a local file path, Compose resource URI, or network URL directly to PagView(path). The library loads asynchronously; nothing renders until ready and load failures are logged, not thrown.

```kotlin
import androidx.compose.foundation.layout.size
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import io.github.limuyang2.libpag.cmp.PagScaleMode
import io.github.limuyang2.libpag.cmp.PagView

@Composable
fun RemoteAnimation(url: String) {
    PagView(
        path = url,
        modifier = Modifier.size(160.dp),
        scaleMode = PagScaleMode.LetterBox,
    )
}
```

--------------------------------

### PagView(path)

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Creates a PagView from a local file path or a network URL. The path can be a local file path (e.g., from Res.getUri()) or a remote URL.

```APIDOC
## PagView(path)

### Description
Creates a PagView from a local file path or a network URL. The path can be a local file path (e.g., from Res.getUri()) or a remote URL.

### Parameters
- **path** (String) - Required - The local file path or network URL of the PAG file.

### Usage Example
```kotlin
val path = Res.getUri("files/loading_bmp.pag")
PagView(path)
```
```

--------------------------------

### Load PAG from bytes with PagView

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Pass raw PAG file bytes to PagView. This is the most portable loading mode and works on all supported targets.

```kotlin
import androidx.compose.foundation.layout.size
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import io.github.limuyang2.libpag.cmp.PagScaleMode
import io.github.limuyang2.libpag.cmp.PagView

@Composable
fun LoadingAnimation(bytes: ByteArray) {
    PagView(
        bytes = bytes,
        modifier = Modifier.size(160.dp),
        isPlaying = true,
        repeatCount = 0,
        scaleMode = PagScaleMode.LetterBox,
    )
}
```

--------------------------------

### Basic example: preview conversion on Android

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/path-convert.md

Shows how to call pathConvert directly to preview the normalized path. On Android, file:///android_asset/splash_anim.pag becomes assets://splash_anim.pag; other platforms leave it unchanged.

```kotlin
import io.github.limuyang2.libpag.cmp.pathConvert

val nativePath = pathConvert("file:///android_asset/splash_anim.pag")
// Android: "assets://splash_anim.pag"  (other platforms: unchanged)
```

--------------------------------

### Generate POM for WasmJS Publication

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Generates the POM file for the WasmJS publication to check publication metadata.

```shell
./gradlew :lib-pag-cmp:generatePomFileForWasmJsPublication
```

--------------------------------

### PagView(bytes)

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Creates a PagView from a ByteArray containing PAG file data. The ByteArray is typically obtained via Res.readBytes().

```APIDOC
## PagView(bytes)

### Description
Creates a PagView from a ByteArray containing PAG file data. The ByteArray is typically obtained via Res.readBytes().

### Parameters
- **bytes** (ByteArray) - Required - The PAG file data as a ByteArray.

### Usage Example
```kotlin
val bytes = Res.readBytes("files/8.pag")
PagView(bytes)
```
```

--------------------------------

### Load local .pag file from Compose resources

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Read a .pag file from src/commonMain/composeResources/files/ using the Compose Multiplatform resource API and pass the bytes to PagView. Requires the components-resources dependency and the generated Res class.

```kotlin
import androidx.compose.foundation.layout.size
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import io.github.limuyang2.libpag.cmp.PagScaleMode
import io.github.limuyang2.libpag.cmp.PagView
import org.jetbrains.compose.resources.ExperimentalResourceApi
// `Res` is generated by the Compose resources plugin; its package follows your module setup.
import your.module.generated.resources.Res

@OptIn(ExperimentalResourceApi::class)
@Composable
fun LocalAnimation() {
    var bytes by remember { mutableStateOf<ByteArray?>(null) }
    LaunchedEffect(Unit) {
        bytes = Res.readBytes("files/loading.pag")
    }
    bytes?.let {
        PagView(
            bytes = it,
            modifier = Modifier.size(160.dp),
            scaleMode = PagScaleMode.LetterBox,
        )
    }
}
```

--------------------------------

### Add lib-pag-cmp dependency in Kotlin DSL

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Configure the Maven Central repository and add the common KMP artifact to the commonMain source set. Use version 0.1.6.

```kotlin
repositories {
    mavenCentral()
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.limuyang2:lib-pag-cmp:0.1.6")
        }
    }
}
```

--------------------------------

### Basic usage: choose a fit mode

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-scale-mode.md

Shows how to pass a scale mode to PagView. The example uses PagScaleMode.Zoom to cover the area and crop overflow.

```kotlin
import androidx.compose.foundation.layout.size
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import io.github.limuyang2.libpag.cmp.PagScaleMode
import io.github.limuyang2.libpag.cmp.PagView

@Composable
fun ZoomedAnimation(bytes: ByteArray) {
    PagView(
        bytes = bytes,
        modifier = Modifier.size(160.dp),
        scaleMode = PagScaleMode.Zoom, // covers the area, crops overflow
        isPlaying = true,
    )
}
```

--------------------------------

### Reuse loaded PAG composition with Pag.load

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

On Android, iOS, and JVM, load a composition once with Pag.load(bytes) and pass it to PagView(composition) to avoid repeated loading. Remember to close the composition with DisposableEffect. Not supported on Web targets.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.remember
import io.github.limuyang2.libpag.cmp.Pag
import io.github.limuyang2.libpag.cmp.PagView

@Composable
fun ReusedAnimation(bytes: ByteArray) {
    val composition = remember(bytes) { Pag.load(bytes) }

    DisposableEffect(composition) {
        onDispose { composition.close() }
    }

    PagView(composition = composition)
}
```

--------------------------------

### Scale Modes

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Scale modes control how PAG content fits inside the render area. Each mode has distinct behavior for scaling and cropping.

```APIDOC
## Scale Modes

### Description
Scale modes control how PAG content fits inside the render area. Each mode has distinct behavior for scaling and cropping.

### Values
- **None** - Keeps the composition at its original size and position.
- **Stretch** - Scales width and height independently to fill the render area. Content may be distorted.
- **LetterBox** - Scales uniformly until the whole composition is visible. Empty space may remain on one axis.
- **Zoom** - Scales uniformly until the render area is fully covered. Content may be cropped on one axis.
```

--------------------------------

### JVM Runtime Native File System Properties

Source: https://github.com/limuyang2/pag-cmp/blob/main/README.md

Set these JVM system properties to supply external native libpag files for local debugging. The library extracts bundled native files from the jar and loads them with System.load() at runtime.

```shell
-Dlibpag.cmp.libpag=/path/to/libpag
-Dlibpag.cmp.bridge=/path/to/libpag_cmp_jvm.dylib
```

--------------------------------

### Run web demo builds

Source: https://github.com/limuyang2/pag-cmp/blob/main/AGENTS.md

Build the web demo applications for JavaScript and WebAssembly targets.

```shell
./gradlew :webApp:jsBrowserDevelopmentWebpack
./gradlew :webApp:wasmJsBrowserDevelopmentWebpack
```

--------------------------------

### Manual ownership without PagView (JVM)

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-composition.md

Function that manually loads a PAG file, creates a player, sets the composition, seeks to 25% progress, renders to an ImageBitmap, and closes both player and composition in a finally block.

```kotlin
import io.github.limuyang2.libpag.cmp.Pag
import io.github.limuyang2.libpag.cmp.PagPlayer
import io.github.limuyang2.libpag.cmp.PagSize

fun renderFrame(bytes: ByteArray, outputSize: PagSize): androidx.compose.ui.graphics.ImageBitmap {
    val composition = Pag.load(bytes)
    val player: PagPlayer = Pag.createPlayer()
    return try {
        player.composition = composition
        player.progress = 0.25
        player.render(outputSize)
    } finally {
        player.close()
        composition.close()
    }
}
```

--------------------------------

### Run tests and generate POM

Source: https://github.com/limuyang2/pag-cmp/blob/main/AGENTS.md

Run all tests with `./gradlew test` and generate the POM file for publication metadata checks.

```shell
./gradlew test
```

```shell
./gradlew :lib-pag-cmp:generatePomFileForWasmJsPublication
```

--------------------------------

### Render one frame to an ImageBitmap (JVM only)

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-player.md

JVM target only — Pag.createPlayer() is unsupported elsewhere. Loads a PAG file, creates a player, sets progress and scale mode, disables cache for a one-shot render, and returns an ImageBitmap. The player and composition are closed in a finally block.

```kotlin
// JVM target only — Pag.createPlayer() is unsupported elsewhere.
import io.github.limuyang2.libpag.cmp.Pag
import io.github.limuyang2.libpag.cmp.PagPlayer
import io.github.limuyang2.libpag.cmp.PagScaleMode
import io.github.limuyang2.libpag.cmp.PagSize
import io.github.limuyang2.libpag.cmp.requireComposition

fun previewFrame(bytes: ByteArray, progress: Double): androidx.compose.ui.graphics.ImageBitmap {
    val composition = Pag.load(bytes)
    val player = Pag.createPlayer()
    return try {
        player.composition = composition
        player.progress = progress        // 0.0..1.0
        player.scaleMode = PagScaleMode.Zoom
        player.cacheEnabled = false       // disable render cache for a one-shot
        player.render(PagSize(480, 480))
    } finally {
        player.close()
        composition.close()
    }
}
```

--------------------------------

### Basic load, inspect, render via PagView

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-composition.md

Composable function that loads a PAG file, queries its duration and intrinsic size, and renders it in a PagView. Closes the composition on dispose.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.DisposableEffect
import androidx.compose.runtime.remember
import io.github.limuyang2.libpag.cmp.Pag
import io.github.limuyang2.libpag.cmp.PagComposition
import io.github.limuyang2.libpag.cmp.PagView

@Composable
fun SizedAnimation(bytes: ByteArray) {
    val composition = remember(bytes) { Pag.load(bytes) }

    DisposableEffect(composition) {
        onDispose { composition.close() }
    }

    // Query metadata before rendering
    val durationMs = composition.durationUs / 1_000L
    val size = composition.intrinsicSize // PagSize(width, height)

    PagView(
        composition = composition,
        isPlaying = true,
        repeatCount = 1, // play once, then stop
    )
    // `durationMs` / `size` can drive UI text, layout, etc.
}
```

--------------------------------

### Compile library for all platforms

Source: https://github.com/limuyang2/pag-cmp/blob/main/AGENTS.md

Run these Gradle tasks from the repository root to compile the library module for each target platform.

```shell
./gradlew :lib-pag-cmp:compileAndroidMain
./gradlew :lib-pag-cmp:compileKotlinJvm
./gradlew :lib-pag-cmp:compileKotlinJs
./gradlew :lib-pag-cmp:compileKotlinWasmJs
./gradlew :lib-pag-cmp:compileKotlinIosArm64
./gradlew :lib-pag-cmp:compileKotlinIosSimulatorArm64
```

--------------------------------

### fun createPlayer(): PagPlayer

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag.md

Creates a reusable player. A player owns render state such as progress and cache settings.

```APIDOC
## [FUNCTION] createPlayer

### Description
Creates a reusable player. A player owns render state such as progress and cache settings.

### Method
Function call

### Endpoint
Pag.createPlayer()

### Parameters
None

### Return Type
PagPlayer — a player object for rendering PAG compositions.
```

--------------------------------

### fun createPlayer(): PagPlayer

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag.md

Creates a reusable PagPlayer that owns render state and renders a composition into an offscreen ImageBitmap. This function is only supported on the JVM platform; on other platforms it throws an UnsupportedOperationException.

```APIDOC
## `fun createPlayer(): PagPlayer`

### Description
Creates a reusable [`PagPlayer`](pag-player.md) that owns render state (progress, scale mode, cache flags) and renders a composition into an offscreen `ImageBitmap`.

### Return type
`PagPlayer` — assign `composition`, set `progress`/`scaleMode`/`cacheEnabled`, call `render(size)`, and `close()` when done.

### Platform behavior

| Platform | Implementation | Notes |
| --- | --- | --- |
| Android (`Pag.android.kt:10`) | `unsupportedPagPlatform("Android")` | Throws `UnsupportedOperationException`. The Android target renders exclusively through the native `PAGView` inside [`PagView`](pag-view.md); there is no offscreen player path. |
| iOS (`Pag.ios.kt:20`) | `unsupportedPagPlatform("iOS")` | Throws `UnsupportedOperationException`. Same reasoning as Android. |
| JVM (`Pag.jvm.kt:12`) | `JvmPagNative.createPlayer()` → `JvmPagPlayer(handle)` | `check(handle != 0L) { "Failed to create PAG player." }` throws `IllegalStateException` on failure. This is the **only** platform where `createPlayer()` works. The JVM `PagView` uses it internally for its offscreen render loop. |
| JS (`Pag.js.kt:7`) | `unsupportedPagPlatform("JS")` | Throws `UnsupportedOperationException`. |
| WasmJS (`Pag.wasmJs.kt:7`) | `unsupportedPagPlatform("WasmJS")` | Throws `UnsupportedOperationException`. |

### Throws

| Error type | Condition |
|-----------|-----------|
| `IllegalStateException` | JVM: native `createPlayer` returned handle `0` (`"Failed to create PAG player."`) |
| `UnsupportedOperationException` | Android, iOS, JS, WasmJS |
```

--------------------------------

### Debug with external libpag and bridge via JAVA_TOOL_OPTIONS

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/configuration.md

Sets the JVM system properties `libpag.cmp.libpag` and `libpag.cmp.bridge` to point to external native binaries, bypassing the bundled resources for local debugging. The bridge property, when set, is loaded instead of the bundled bridge. Any `UnsatisfiedLinkError` is wrapped in an `IllegalStateException` with a message that includes the platform and suggests setting these properties.

```shell
JAVA_TOOL_OPTIONS='-Dlibpag.cmp.libpag=/private/tmp/libpag-build/libpag.framework/Versions/A/libpag -Dlibpag.cmp.bridge=/private/tmp/pag-cmp-bridge-build/libpag_cmp_jvm.dylib' ./gradlew :desktopApp:run
```

--------------------------------

### Pag.createPlayer

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/index.md

Creates a new PagPlayer instance for playing PAG compositions. This method is only supported on JVM; other platforms throw UnsupportedOperationException.

```APIDOC
## Pag.createPlayer

### Description
Creates a new PagPlayer instance for playing PAG compositions. This method is only supported on JVM; other platforms throw UnsupportedOperationException.

### Method
Function call

### Signature
`Pag.createPlayer(): PagPlayer`

### Returns
- `PagPlayer` - A new player instance.

### Supported Platforms
JVM only
```

--------------------------------

### Render at explicit size

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-size.md

Loads a Pag composition, creates a player, and renders to a bitmap at a specified PagSize of 640x360.

```kotlin
import io.github.limuyang2.libpag.cmp.Pag
import io.github.limuyang2.libpag.cmp.PagSize

val composition = Pag.load(bytes)
val player = Pag.createPlayer()
player.composition = composition
val bitmap = player.render(PagSize(width = 640, height = 360))
```

--------------------------------

### Pag.createPlayer

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/types.md

Creates a new PagPlayer instance. This is a factory method that returns a PagPlayer. Note: JVM only; other platforms throw.

```APIDOC
## [FUNCTION] createPlayer

### Description
Creates a new PagPlayer instance. JVM only; other platforms throw.

### Method
createPlayer

### Endpoint
Pag.createPlayer(): PagPlayer

### Parameters
None

### Response
#### Success Response
- **PagPlayer** - A new PagPlayer instance.

#### Response Example
```kotlin
val player: PagPlayer = Pag.createPlayer()
```
```

--------------------------------

### fun load(bytes: ByteArray, filePath: String? = null): PagComposition

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag.md

Decodes a PAG file from raw bytes and returns a platform-backed PagComposition. The filePath parameter is optional metadata for native decoders.

```APIDOC
## [FUNCTION] load

### Description
Decodes a PAG file from raw bytes and returns a platform-backed PagComposition. The filePath parameter is optional metadata for native decoders.

### Method
Function call

### Endpoint
Pag.load(bytes, filePath)

### Parameters
#### Function Parameters
- **bytes** (ByteArray) - Required - Raw `.pag` file contents.
- **filePath** (String?) - Optional - Metadata passed to the native decoder; used for cache keys or diagnostics.

### Return Type
PagComposition — an opaque handle exposing durationUs, width, height; caller must call close() when done.

### Throws
- **IllegalArgumentException** - Android/iOS: native decode returned null ("Invalid PAG bytes."); iOS: empty bytes ("PAG bytes must not be empty."). JVM: JNI bridge rejects null/empty bytes or null PAGFile result.
- **IllegalStateException** - JVM: native loadFile returned handle 0 ("Failed to load PAG composition.")
- **UnsupportedOperationException** - JS / WasmJS (message: "PAG rendering is not implemented for JS yet...")

### Platform Behavior
| Platform | Implementation | Notes |
| --- | --- | --- |
| Android | PAGFile.Load(bytes) wrapped in AndroidPagComposition | requireNotNull(...) throws IllegalArgumentException when native loader returns null. filePath not forwarded. close() is no-op. |
| iOS | bytes.usePinned { PAGFile.Load(pinned.addressOf(0), bytes.size.convert()) } | require(bytes.isNotEmpty()) throws IllegalArgumentException for empty input; requireNotNull(pagFile) for null result. close() is no-op. |
| JVM | JvmPagNative.loadFile(bytes, filePath) | Returns JvmPagComposition(handle). check(handle != 0L) throws IllegalStateException when native side fails. filePath forwarded to JNI bridge. close() releases native handle. |
| JS | unsupportedPagPlatform("JS") | Always throws UnsupportedOperationException. |
| WasmJS | unsupportedPagPlatform("WasmJS") | Always throws UnsupportedOperationException. |
```

--------------------------------

### PagView(path: String, ...)

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-view.md

Renders a PAG animation from a local file path, a Compose resource URI, or an http/https URL. Loading is asynchronous; nothing renders until the file is ready and a load failure is logged (not thrown).

```APIDOC
## PagView(path: String, ...)

### Description
Renders a PAG animation from a local file path, a Compose resource URI, or an http/https URL. Loading is asynchronous; nothing renders until the file is ready and a load failure is logged (not thrown).

### Signature
```kotlin
@Composable
expect fun PagView(
    path: String,
    modifier: Modifier = Modifier,
    isPlaying: Boolean = true,
    progress: Double? = null,
    repeatCount: Int = 0,
    scaleMode: PagScaleMode = PagScaleMode.LetterBox,
    cacheEnabled: Boolean = true,
    videoEnabled: Boolean = true,
    useDiskCache: Boolean = false,
)
```

### Parameters
- **path** (String) - Required - Local file path, Compose resource URI, or http/https URL.
- **modifier** (Modifier) - Optional - Compose modifier for layout and styling.
- **isPlaying** (Boolean) - Optional - Whether the animation is playing. Defaults to true.
- **progress** (Double?) - Optional - Current animation progress (0.0 to 1.0). If null, uses internal playback.
- **repeatCount** (Int) - Optional - Number of times to repeat the animation. 0 means infinite.
- **scaleMode** (PagScaleMode) - Optional - How the animation scales to fit the view. Defaults to LetterBox.
- **cacheEnabled** (Boolean) - Optional - Whether to enable caching. Defaults to true.
- **videoEnabled** (Boolean) - Optional - Whether video decoding is enabled. Defaults to true.
- **useDiskCache** (Boolean) - Optional - Whether to use disk cache. Defaults to false.

### Usage
```kotlin
PagView(path = "https://example.com/animation.pag")
```
```

--------------------------------

### Pag.load

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/types.md

Loads a PagComposition from a byte array or a file path. This is a static method on the Pag object.

```APIDOC
## [FUNCTION] load

### Description
Loads a PagComposition from a byte array or a file path.

### Method
load

### Endpoint
Pag.load(data: ByteArray, path: String? = null): PagComposition

### Parameters
#### Parameters
- **data** (ByteArray) - Required - The byte array containing the PAG file data.
- **path** (String?) - Optional - The file path to load from; if provided, data may be ignored.

### Response
#### Success Response
- **PagComposition** - The loaded composition.

#### Response Example
```kotlin
val composition: PagComposition = Pag.load(bytes)
```
```

--------------------------------

### render(size: PagSize): ImageBitmap

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-player.md

Renders the current progress into an offscreen bitmap with the requested pixel size. Returns an ImageBitmap holding the rendered frame.

```APIDOC
## render(size: PagSize): ImageBitmap

### Description
Renders the current `progress` into an offscreen bitmap with the requested pixel size.

### Method
Function call

### Parameters
#### Parameters
- **size** (`PagSize`) - Optional - Default: `requireComposition().intrinsicSize` - Output pixel dimensions. `PagSize` validates `width > 0` and `height > 0` in its `init` block.

### Return
`ImageBitmap` (`androidx.compose.ui.graphics.ImageBitmap`) holding the rendered frame.

### Throws
- `IllegalStateException` - No composition set — `requireComposition()` fails with `"PagPlayer has no composition. Call set composition before rendering."` (via the `error(...)` extension).
- `IllegalStateException` - JVM: player or composition already closed (`"PagPlayer is closed."` / `"PagComposition is closed."`).
- `IllegalStateException` - JVM: `JvmPagNative.renderToBgra` returned `false` — `check(rendered) { "Failed to render PAG frame." }`.
- `IllegalArgumentException` - JVM native: `size` not positive (`"Render size must be positive."`) or the internal pixel buffer too small — thrown by the JNI bridge, see [errors.md](../errors.md).
```

--------------------------------

### PagSize(width: Int, height: Int)

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/types.md

Data class representing a size in pixels. Requires width and height to be greater than 0, otherwise throws IllegalArgumentException.

```APIDOC
## PagSize(width: Int, height: Int)

### Description
Data class representing a size in pixels. Requires width and height to be greater than 0, otherwise throws IllegalArgumentException.

### Constructor
```kotlin
data class PagSize(
    val width: Int,
    val height: Int,
)
```

### Parameters
- **width** (Int) - Required - Width in pixels; must be > 0 or IllegalArgumentException is thrown.
- **height** (Int) - Required - Height in pixels; must be > 0 or IllegalArgumentException is thrown.

### Properties
- **width** (Int) - Width in pixels.
- **height** (Int) - Height in pixels.

### Usage
- Returned by: `PagComposition.intrinsicSize`
- Accepted by: `PagPlayer.render(size: PagSize)`
- Used internally by: JVM `PagView` (from canvas `IntSize`) and `JvmPagFrameBuffer` (buffer allocation key)
```

--------------------------------

### Load PAG from network URL with PagView

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-view.md

Loads a PAG animation from an http(s) URL. Works on any target, but browser targets require CORS. Uses scaleMode Zoom.

```kotlin
@Composable
fun RemoteAnimation(url: String) {
    PagView(
        path = url,                     // http(s) only; browser targets require CORS
        modifier = Modifier.size(160.dp),
        scaleMode = PagScaleMode.Zoom,
    )
}
```

--------------------------------

### JVM-only: offscreen player without a PagView

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag.md

Renders a single frame offscreen using Pag.createPlayer() on the JVM target. On other platforms createPlayer() throws UnsupportedOperationException. The player and composition are closed in a finally block.

```kotlin
import io.github.limuyang2.libpag.cmp.Pag
import io.github.limuyang2.libpag.cmp.PagSize
import io.github.limuyang2.libpag.cmp.PagScaleMode
import io.github.limuyang2.libpag.cmp.requireComposition

fun renderSingleFrame(bytes: ByteArray): androidx.compose.ui.graphics.ImageBitmap {
    val composition = Pag.load(bytes)
    val player = Pag.createPlayer()
    try {
        player.composition = composition
        player.progress = 0.5
        player.scaleMode = PagScaleMode.LetterBox
        return player.render(composition.intrinsicSize)
    } catch (e: IllegalStateException) {
        // "PagPlayer has no composition..." / "PagComposition is closed." /
        // "PagPlayer is closed." / "Failed to render PAG frame."
        throw IllegalStateException("Frame render failed", e)
    } finally {
        player.close()
        composition.close()
    }
}
```

--------------------------------

### CMake configuration for pag_cmp_jvm

Source: https://github.com/limuyang2/pag-cmp/blob/main/lib-pag-cmp/src/jvmMain/cpp/CMakeLists.txt

Builds the pag_cmp_jvm shared library for JVM. Requires LIBPAG_ROOT and LIBPAG_LIBRARY to be set via CMake cache variables. Links against the desktop libpag dynamic library and sets the install/build RPATH to @loader_path on Apple platforms.

```cmake
cmake_minimum_required(VERSION 3.13)
project(pag_cmp_jvm LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

set(LIBPAG_ROOT "" CACHE PATH "Path to a local Tencent/libpag checkout")
set(LIBPAG_LIBRARY "" CACHE FILEPATH "Path to the built desktop libpag dynamic library")

if (NOT LIBPAG_ROOT)
    message(FATAL_ERROR "LIBPAG_ROOT is required, for example -DLIBPAG_ROOT=/Users/mumu/projects/android/libpag")
endif ()

if (NOT LIBPAG_LIBRARY)
    message(FATAL_ERROR "LIBPAG_LIBRARY is required, for example -DLIBPAG_LIBRARY=/path/to/libpag.dylib")
endif ()

find_package(JNI REQUIRED)

add_library(pag_cmp_jvm SHARED pag_cmp_jvm.cpp)

target_include_directories(pag_cmp_jvm PRIVATE
    ${JNI_INCLUDE_DIRS}
    ${LIBPAG_ROOT}/include
)

target_link_libraries(pag_cmp_jvm PRIVATE ${LIBPAG_LIBRARY})

if (APPLE)
    set_target_properties(pag_cmp_jvm PROPERTIES
        INSTALL_RPATH "@loader_path"
        BUILD_RPATH "@loader_path"
    )
endif ()
```

--------------------------------

### PagView Parameters

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-view.md

Describes the configurable parameters for the PagView composable, including overloads for loading PAG content from bytes, composition, or path.

```APIDOC
## PagView Parameters

### Description
PagView is a composable that displays PAG animations. It accepts parameters to control content loading, playback, rendering, and scaling.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `bytes` | `ByteArray` | yes (overload 1) | — | Raw bytes of the `.pag` file. On Android/iOS/JVM the bytes are decoded immediately (synchronously in composition). |
| `composition` | `PagComposition` | yes (overload 2) | — | A composition returned by `Pag.load(bytes)`. The caller owns its lifecycle and should call `close()` when done. JS/WasmJS throw `UnsupportedOperationException`. |
| `path` | `String` | yes (overload 3) | — | Local path, `file:`/`jar:` URI, Compose resource URI (e.g. `Res.getUri("files/name.pag")`), or `http`/`https` URL. Do not pass a raw resource-relative path like `"files/loading_bmp.pag"`. |
| `modifier` | `Modifier` | no | `Modifier` | Compose modifier applied to the view/placeholder. |
| `isPlaying` | `Boolean` | no | `true` | Starts playback when `true`, pauses when `false`. |
| `progress` | `Double?` | no | `null` | Optional manual progress in `0.0..1.0` (internally coerced with `coerceIn(0.0, 1.0)`). When set while paused, `flush()` renders the current frame. |
| `repeatCount` | `Int` | no | `0` | Native libpag repeat count; `0` means infinite repeat. |
| `scaleMode` | `PagScaleMode` | no | `PagScaleMode.LetterBox` | Content fit inside the render area (see [pag-scale-mode.md](pag-scale-mode.md)). Affects only the content transform inside the native renderer, never `PagView` layout bounds. |
| `cacheEnabled` | `Boolean` | no | `true` | Enables libpag render cache. |
| `videoEnabled` | `Boolean` | no | `true` | Enables video-sequence rendering when the PAG file contains video content. |
| `useDiskCache` | `Boolean` | no | `false` | Enables libpag disk cache on platforms that expose it. |
```

--------------------------------

### Switching modes dynamically

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-scale-mode.md

Demonstrates dynamic scale mode switching via Compose state. Recomposition with a new mode re-applies the scale mode on every platform.

```kotlin
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import io.github.limuyang2.libpag.cmp.PagScaleMode
import io.github.limuyang2.libpag.cmp.PagView

@Composable
fun ModeSwitch(bytes: ByteArray) {
    var mode by remember { mutableStateOf(PagScaleMode.LetterBox) }
    // Recomposition with a new `mode` re-applies the scale mode on every
    // platform (update block on native views, LaunchedEffect on JVM/Web).
    PagView(bytes = bytes, scaleMode = mode)
}
```

--------------------------------

### Pag.load

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/index.md

Loads a PAG composition from raw bytes or a file path. Returns a PagComposition instance that can be used with PagView or PagPlayer.

```APIDOC
## Pag.load

### Description
Loads a PAG composition from raw bytes or a file path. Returns a PagComposition instance that can be used with PagView or PagPlayer.

### Method
Function call

### Signature
`Pag.load(bytes: ByteArray, filePath: String? = null): PagComposition`

### Parameters
- `bytes` (ByteArray) - Required - The raw PAG file data.
- `filePath` (String?) - Optional - The file path to load from. If provided, the bytes parameter may be ignored.

### Returns
- `PagComposition` - The loaded composition.

### Supported Platforms
Android, iOS, JVM
```

--------------------------------

### PagComposition Properties

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-composition.md

Read-only properties exposing the composition's duration, dimensions, and a convenience intrinsic size accessor.

```APIDOC
## Properties

### durationUs
- Type: Long
- Description: Total animation duration in microseconds.

### width
- Type: Int
- Description: Composition width in pixels.

### height
- Type: Int
- Description: Composition height in pixels.

### intrinsicSize
- Type: PagSize
- Description: Default getter: PagSize(width, height). Convenience accessor used as the default render size for PagPlayer.render().
```

--------------------------------

### Error handling per failure class

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-player.md

Catches IllegalStateException when rendering a PAG frame. The default render size is composition.intrinsicSize. The catch block prints the error message and returns null; the player and composition are closed in a finally block.

```kotlin
import io.github.limuyang2.libpag.cmp.Pag

fun safeFrame(bytes: ByteArray): androidx.compose.ui.graphics.ImageBitmap? {
    val composition = Pag.load(bytes)
    val player = Pag.createPlayer()
    return try {
        player.composition = composition
        player.render() // default size = composition.intrinsicSize
    } catch (e: IllegalStateException) {
        // "PagPlayer has no composition...", "PagPlayer is closed.",
        // "PagComposition is closed.", "Failed to render PAG frame."
        println("render failed: ${e.message}")
        null
    } finally {
        player.close()
        composition.close()
    }
}
```

--------------------------------

### iOS actual implementation of pathConvert

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/path-convert.md

iOS implementation: http(s) URLs pass through unchanged; a leading file:// prefix is stripped so the native PAGView.setPathAsync receives a plain filesystem path.

```kotlin
actual fun pathConvert(path: String): String {
    if (path.isHttpUrl()) return path
    return path.removePrefix(IosFileUriPrefix)
}

private const val IosFileUriPrefix = "file://"
```

--------------------------------

### Progress scrubbing while paused with PagView

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-view.md

Shows how to scrub through a PAG animation while paused. Setting isPlaying to false makes each progress change flush one frame; progress is a Float in 0.0..1.0.

```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import io.github.limuyang2.libpag.cmp.PagView

@Composable
fun ScrubbedPreview(bytes: ByteArray) {
    var progress by remember { mutableStateOf(0.0) }

    PagView(
        bytes = bytes,
        modifier = Modifier.fillMaxSize(),
        isPlaying = false,              // paused: each progress change flushes one frame
        progress = progress,            // 0.0..1.0
    )
}
```

--------------------------------

### PagView (path)

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/index.md

Composable function that displays a PAG animation from a file path. Supported on all targets.

```APIDOC
## PagView(path: String, ...)

### Description
Composable function that displays a PAG animation from a file path. Supported on all targets.

### Method
Composable function

### Signature
`@Composable fun PagView(path: String, ...)`

### Parameters
- `path` (String) - Required - The file path to the PAG file.
- Additional parameters as defined by the composable function.

### Supported Platforms
All targets
```

--------------------------------

### PagPlayer interface definition

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-player.md

Defines the PagPlayer interface with properties for composition, progress, scale mode, and cache, plus a render method that outputs an offscreen ImageBitmap.

```kotlin
interface PagPlayer : PagCloseable {
    var composition: PagComposition?
    var progress: Double
    var scaleMode: PagScaleMode
    var cacheEnabled: Boolean

    /**
     * Renders the current [progress] into an offscreen bitmap.
     */
    fun render(size: PagSize = requireComposition().intrinsicSize): ImageBitmap
}
```

--------------------------------

### PagCloseable.close()

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/types.md

Releases underlying native resources. Implementations are expected to be idempotent.

```APIDOC
## PagCloseable.close()

### Description
Releases underlying native resources. Implementations are expected to be idempotent.

### Method
close()

### Signature
```kotlin
fun close()
```

### Parameters
None

### Returns
Unit

### Notes
- Implementors: `PagComposition`, `PagPlayer`, and their platform implementations.
- Consumed by: `DisposableEffect { onDispose { ... close() } }` patterns in `PagView` usage.
```

--------------------------------

### PagView(composition: PagComposition, ...)

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-view.md

Renders a PAG animation from a pre-loaded PagComposition. This allows reusing a single decode across multiple PagView instances. Note: Unsupported on JS and WasmJS targets; calling it throws UnsupportedOperationException.

```APIDOC
## PagView(composition: PagComposition, ...)

### Description
Renders a PAG animation from a pre-loaded PagComposition. This allows reusing a single decode across multiple PagView instances. Note: Unsupported on JS and WasmJS targets; calling it throws UnsupportedOperationException.

### Signature
```kotlin
@Composable
expect fun PagView(
    composition: PagComposition,
    modifier: Modifier = Modifier,
    isPlaying: Boolean = true,
    progress: Double? = null,
    repeatCount: Int = 0,
    scaleMode: PagScaleMode = PagScaleMode.LetterBox,
    cacheEnabled: Boolean = true,
    videoEnabled: Boolean = true,
    useDiskCache: Boolean = false,
)
```

### Parameters
- **composition** (PagComposition) - Required - A composition previously loaded with `Pag.load(bytes)`.
- **modifier** (Modifier) - Optional - Compose modifier for layout and styling.
- **isPlaying** (Boolean) - Optional - Whether the animation is playing. Defaults to true.
- **progress** (Double?) - Optional - Current animation progress (0.0 to 1.0). If null, uses internal playback.
- **repeatCount** (Int) - Optional - Number of times to repeat the animation. 0 means infinite.
- **scaleMode** (PagScaleMode) - Optional - How the animation scales to fit the view. Defaults to LetterBox.
- **cacheEnabled** (Boolean) - Optional - Whether to enable caching. Defaults to true.
- **videoEnabled** (Boolean) - Optional - Whether video decoding is enabled. Defaults to true.
- **useDiskCache** (Boolean) - Optional - Whether to use disk cache. Defaults to false.

### Usage
```kotlin
val composition = Pag.load(bytes)
PagView(composition = composition)
```
```

--------------------------------

### Handling user-supplied paths before calling PagView(path)

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/path-convert.md

Composable that normalizes a user-supplied URI with pathConvert before passing it to PagView(path). Native views also re-normalize internally.

```kotlin
import androidx.compose.runtime.Composable
import io.github.limuyang2.libpag.cmp.PagView
import io.github.limuyang2.libpag.cmp.pathConvert

@Composable
fun AssetAnimation(uri: String) {
    // Normalize, then let PagView(path) display it (native views also re-normalize internally).
    PagView(path = pathConvert(uri))
}
```

--------------------------------

### PagPlayer.requireComposition extension

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-player.md

Extension function that returns the composition or throws an error if none is set. Use before rendering to ensure a composition exists.

```kotlin
fun PagPlayer.requireComposition(): PagComposition =
    composition ?: error("PagPlayer has no composition. Call set composition before rendering.")
```

--------------------------------

### PagView(path)

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/types.md

A Composable function that displays a PAG animation from a file path. This is a UI component that can be used in Compose.

```APIDOC
## [COMPOSABLE] PagView(path)

### Description
A Composable function that displays a PAG animation from a file path.

### Method
PagView

### Endpoint
PagView(path: String, modifier: Modifier = Modifier, autoPlay: Boolean = true, progress: Double? = null, repeatCount: Int = 0, scaleMode: PagScaleMode = PagScaleMode.LetterBox, cacheEnabled: Boolean = true, videoEnabled: Boolean = true, useDiskCache: Boolean = false)

### Parameters
#### Parameters
- **path** (String) - Required - The file path to the PAG file.
- **modifier** (Modifier) - Optional - Compose modifier.
- **autoPlay** (Boolean) - Optional - Whether to auto-play the animation.
- **progress** (Double?) - Optional - Initial progress value.
- **repeatCount** (Int) - Optional - Number of times to repeat the animation.
- **scaleMode** (PagScaleMode) - Optional - Content fit mode.
- **cacheEnabled** (Boolean) - Optional - Whether to enable caching.
- **videoEnabled** (Boolean) - Optional - Whether video is enabled.
- **useDiskCache** (Boolean) - Optional - Whether to use disk cache.

### Response
#### Success Response
- **Unit** - Composable function returns Unit.

#### Response Example
```kotlin
PagView(path = "path/to/file.pag")
```
```

--------------------------------

### PagPlayer.render

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-player.md

Renders the current progress into an offscreen ImageBitmap. The size can be specified or defaults to the composition's intrinsic size.

```APIDOC
## [Kotlin] PagPlayer.render

### Description
Renders the current progress into an offscreen bitmap.

### Method
fun render(size: PagSize = requireComposition().intrinsicSize): ImageBitmap

### Parameters
- **size** (PagSize) - Optional - The size of the output bitmap. Defaults to the composition's intrinsic size.

### Return Value
- **ImageBitmap** - The rendered offscreen bitmap.

### Example
```kotlin
val bitmap = player.render()
```
```

--------------------------------

### PagComposition interface definition

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/pag-composition.md

Defines the PagComposition interface with durationUs, width, height, and intrinsicSize properties. intrinsicSize has a default getter returning PagSize(width, height).

```kotlin
interface PagComposition : PagCloseable {
    val durationUs: Long
    val width: Int
    val height: Int

    val intrinsicSize: PagSize
        get() = PagSize(width, height)
}
```

--------------------------------

### pathConvert expect function signature

Source: https://github.com/limuyang2/pag-cmp/blob/main/_autodocs/api-reference/path-convert.md

Declares the public expect function that normalizes a path/URI string before it is handed to a platform loader. Consumers may call it directly to preview how a path will be rewritten on the current platform.

```kotlin
expect fun pathConvert(path: String): String
```
Tokens:
Raw