From 2f9726128ac257a043aefb9ed9c70d169a88a736 Mon Sep 17 00:00:00 2001 From: Jordon de Hoog Date: Sat, 16 Sep 2023 19:47:15 -0400 Subject: [PATCH] add READMEs for the extensions --- README.md | 37 +++++++++++++---- extensions-base64/README.md | 58 ++++++++++++++++++++++++++ extensions-bytearray/README.md | 33 +++++++++++++++ extensions-libres/README.md | 45 +++++++++++++++++++++ extensions-network/README.md | 74 ++++++++++++++++++++++++++++++++++ extensions-resources/README.md | 59 +++++++++++++++++++++++++++ 6 files changed, 299 insertions(+), 7 deletions(-) create mode 100644 extensions-base64/README.md create mode 100644 extensions-bytearray/README.md create mode 100644 extensions-libres/README.md create mode 100644 extensions-network/README.md create mode 100644 extensions-resources/README.md diff --git a/README.md b/README.md index 552e698..06ac095 100644 --- a/README.md +++ b/README.md @@ -196,13 +196,36 @@ the [demo app](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/palet In order to generate a color palette, you must first have an `ImageBitmap` object. This library provides some extensions artifacts for some popular sources. -| Artifact | Library | Loader | Input Class | Desktop | Android | iOS | Demo | -|------------------------|------------------------------------------------------------------------------------------------------------------------|-------------------|-------------|:-------:|:-------:|:---:|---------------------------------------------------------------------------------------------------------------------------| -| `extensions-base64` | N/A | `Base64Loader` | `String` | ✅ | ✅ | ✅ | [`Base64DemoScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/dominant/Base64DemoScreen.kt) | -| `extensions-bytearray` | N/A | `ByteArrayLoader` | `ByteArray` | ✅ | ✅ | ✅ | N/A | -| `extensions-libres` | [libres](https://github.com/Skeptick/libres) | `LibresLoader` | `Image` | ✅ | ✅ | ✅ | [`LibresPaletteScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/palette/LibresPaletteScreen.kt) | -| `extensions-network` | [ktor](https://github.com/ktorio/ktor) | `NetworkLoader` | `Url` | ✅ | ✅ | ✅ | [`NetworkDemoScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/dominant/NetworkDemoScreen.kt) | -| `extensions-resources` | [Compose Multiplatform Resources](https://github.com/JetBrains/compose-multiplatform/tree/master/components/resources) | `ResourceLoader` | `Resource` | ✅ | ✅ | ✅ | [`ResourcesPaletteScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/palette/ResourcesPaletteScreen.kt) | +| Artifact | Library | Loader | Input Class | Demo | +|:--------------------------------------------------------:|------------------------------------------------------------------------------------------------------------------------|-------------------|-------------|---------------------------------------------------------------------------------------------------------------------------| +| [`extensions-base64`](extensions-base64/README.md) | N/A | `Base64Loader` | `String` | [`Base64DemoScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/dominant/Base64DemoScreen.kt) | +| [`extensions-bytearray`](extensions-bytearray/README.md) | N/A | `ByteArrayLoader` | `ByteArray` | N/A | +| [`extensions-libres`](extensions-libres/README.md) | [libres](https://github.com/Skeptick/libres) | `LibresLoader` | `Image` | [`LibresPaletteScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/palette/LibresPaletteScreen.kt) | +| [`extensions-network`](extensions-network/README.md) | [ktor](https://github.com/ktorio/ktor) | `NetworkLoader` | `Url` | [`NetworkDemoScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/dominant/NetworkDemoScreen.kt) | +| [`extensions-resources`](extensions-resources/README.md) | [Compose Multiplatform Resources](https://github.com/JetBrains/compose-multiplatform/tree/master/components/resources) | `ResourceLoader` | `Resource` | [`ResourcesPaletteScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/palette/ResourcesPaletteScreen.kt) | + +Each of these extensions provides a `ImageBitmapLoader` object that can be used to generate +an `ImageBitmap` from the input class. For example, the `NetworkLoader` can be used to generate +an `ImageBitmap` from a `Url`: + +```kotlin +@Composable +fun SomeComposable(url: Url) { + val dominantColorState = rememberDominantColorState(loader = NetworkLoader()) + LaunchedEffect(url) { + dominantColorState.updateFrom(url) + } + + Box( + modifier = Modifier + .width(200.dp) + .height(100.dp) + .background(dominantColorState.color) + ) { + Text("Some Text", color = dominantColorState.onColor) + } +} +``` ## Demo diff --git a/extensions-base64/README.md b/extensions-base64/README.md new file mode 100644 index 0000000..b3ac676 --- /dev/null +++ b/extensions-base64/README.md @@ -0,0 +1,58 @@ +# Base64 Extensions + +This extension provides `Base64Loader` a `ImageBitmapLoader` for loading base64 encoded images to a `ImageBitmap`. + +| Loader | Input Class | Demo | +|----------------|-------------|----------------------------------------------------------------------------------------------------------------| +| `Base64Loader` | `String` | [`Base64DemoScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/dominant/Base64DemoScreen.kt) | + +# Setup + +You need to add the following to your `build.gradle.kts` file: + +```kotlin +kotlin { + sourceSets { + commonMain { + dependencies { + implementation(libs.kmpalette.core) + implementation(libs.kmpalette.extensions.base64) + } + } + } +} +``` + +## Usage + +You will need to have a image (png, jpg, etc) encoded as a Base64 `String`. You can then +use `Base64Loader` to load the image. + +**Note:** If there is a header on the Base64 `String` it will be stripped and ignored. + +```kotlin +val base64Image = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAAD" + + "gdz34AAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAApgAAAKYB3X3/OAAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3" + + "NjYXBlLm9yZ5vuPBoAAANCSURBVEiJtZZPbBtFFMZ/M7ubXdtdb1xSFyeilBapySVU8h8OoFaooFSqiihIVIpQB" + + "Kci6KEg9Q6H9kovIHoCIVQJJCKE1ENFjnAgcaSGC6rEnxBwA04Tx43t2FnvDAfjkNibxgHxnWb2e/u992bee7tC" + + "a00YFsffekFY+nUzFtjW0LrvjRXrCDIAaPLlW0nHL0SsZtVoaF98mLrx3pdhOqLtYPHChahZcYYO7KvPFxvRl5X" + + "Pp1sN3adWiD1ZAqD6XYK1b/dvE5IWryTt2udLFedwc1+9kLp+vbbpoDh+6TklxBeAi9TL0taeWpdmZzQDry0AcO" + + "+jQ12RyohqqoYoo8RDwJrU+qXkjWtfi8Xxt58BdQuwQs9qC/afLwCw8tnQbqYAPsgxE1S6F3EAIXux2oQFKm0ih" + + "MsOF71dHYx+f3NND68ghCu1YIoePPQN1pGRABkJ6Bus96CutRZMydTl+TvuiRW1m3n0eDl0vRPcEysqdXn+jsQP" + + "srHMquGeXEaY4Yk4wxWcY5V/9scqOMOVUFthatyTy8QyqwZ+kDURKoMWxNKr2EeqVKcTNOajqKoBgOE28U4tdQl" + + "5p5bwCw7BWquaZSzAPlwjlithJtp3pTImSqQRrb2Z8PHGigD4RZuNX6JYj6wj7O4TFLbCO/Mn/m8R+h6rYSUb3e" + + "kokRY6f/YukArN979jcW+V/S8g0eT/N3VN3kTqWbQ428m9/8k0P/1aIhF36PccEl6EhOcAUCrXKZXXWS3XKd2vc" + + "/TRBG9O5ELC17MmWubD2nKhUKZa26Ba2+D3P+4/MNCFwg59oWVeYhkzgN/JDR8deKBoD7Y+ljEjGZ0sosXVTvbc" + + "6RHirr2reNy1OXd6pJsQ+gqjk8VWFYmHrwBzW/n+uMPFiRwHB2I7ih8ciHFxIkd/3Omk5tCDV1t+2nNu5sxxpDF" + + "Nx+huNhVT3/zMDz8usXC3ddaHBj1GHj/As08fwTS7Kt1HBTmyN29vdwAw+/wbwLVOJ3uAD1wi/dUH7Qei66Pfyu" + + "Rj4Ik9is+hglfbkbfR3cnZm7chlUWLdwmprtCohX4HUtlOcQjLYCu+fzGJH2QRKvP3UNz8bWk1qMxjGTOMThZ3k" + + "vgLI5AzFfo379UAAAAASUVORK5CYII=" + +val imageBitmap: ImageBitmap = Base64Loader.load(base64Image) + +// Or using one of the composeable functions +val paletteState = rememebrPaletteState(Base64Loader) +LaunchedEffect(base64Image) { + paletteState.generate(base64Image) +} +``` \ No newline at end of file diff --git a/extensions-bytearray/README.md b/extensions-bytearray/README.md new file mode 100644 index 0000000..e108abc --- /dev/null +++ b/extensions-bytearray/README.md @@ -0,0 +1,33 @@ +# ByteArray Extensions + +This extension provides `ByteArrayLoader` a `ImageBitmapLoader` for loading image bytes to +a `ImageBitmap`. + +| Loader | Input Class | Demo | +|-------------------|-------------|------| +| `ByteArrayLoader` | `ByteArray` | N/A | + +# Setup + +You need to add the following to your `build.gradle.kts` file: + +```kotlin +kotlin { + sourceSets { + commonMain { + dependencies { + implementation(libs.kmpalette.core) + implementation(libs.kmpalette.extensions.bytearray) + } + } + } +} +``` + +## Usage + +You will need to have a `ByteArray` containing all the bytes of an image. Typically this extension +isn't used directly, but instead used by other extensions that provide a `ByteArray` as an output: + +- `extensions-resources` +- `extensions-network` diff --git a/extensions-libres/README.md b/extensions-libres/README.md new file mode 100644 index 0000000..d9c6302 --- /dev/null +++ b/extensions-libres/README.md @@ -0,0 +1,45 @@ +# Libres Extensions + +This extension provides `LibresLoader` a `ImageBitmapLoader` for +loading [Libres](https://github.com/Skeptick/libres) `Image` objects. + +| Library | Loader | Input Class | Demo | +|----------------------------------------------|----------------|-------------|---------------------------------------------------------------------------------------------------------------------| +| [libres](https://github.com/Skeptick/libres) | `LibresLoader` | `Image` | [`LibresPaletteScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/palette/LibresPaletteScreen.kt) | + +## Setup + +First you need to follow the setup instructions for [Libres](https://github.com/Skeptick/libres). + +Then you need to add the following to your `build.gradle.kts` file: + +```kotlin +kotlin { + sourceSets { + commonMain { + dependencies { + implementation(libs.kmpalette.core) + implementation(libs.kmpalette.extensions.libres) + } + } + } +} +``` + +**Warning:** Although Libres supports XML and SVG vector images, this library does not. It will +crash if you attempt to use a vector format. + +## Usage + +Add your images to the `libres/images` folder in the `commonMain` source set. You can then load them +using the `LibresLoader`: + +```kotlin +val imageBitmap: ImageBitmap = LibresLoader.load(Res.image.example1) + +// Or using one of the composeable functions +val paletteState = rememebrPaletteState(loader = Base64Loader) +LaunchedEffect(base64Image) { + paletteState.generate(Res.image.example1) +} +``` \ No newline at end of file diff --git a/extensions-network/README.md b/extensions-network/README.md new file mode 100644 index 0000000..8a5220a --- /dev/null +++ b/extensions-network/README.md @@ -0,0 +1,74 @@ +# Network Extensions + +This extension provides `Network` a `ImageBitmapLoader` for loading images from a URL. + +| Library | Loader | Input Class | Demo | +|------------------------------------------------------|----------------------------------------|-----------------|-------| +| [`extensions-network`](extensions-network/README.md) | [ktor](https://github.com/ktorio/ktor) | `NetworkLoader` | `Url` | [`NetworkDemoScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/dominant/NetworkDemoScreen.kt) | + +## Setup + +In order to use these extensions you will need to add the Ktor dependency to +your `build.gradle.kts`, you will need the `core` library as well as a client for each of your +supported platforms. + +Then you need to add the following to your `build.gradle.kts` file: + +```kotlin +kotlin { + sourceSets { + commonMain { + dependencies { + implementation(libs.kmpalette.core) + implementation("io.ktor:ktor-client-core:$ktor_version") + } + } + + androidMain { + dependencies { + implementation("io.ktor:ktor-client-android:$ktor_version") + } + } + + iosMain { + dependencies { + implementation("io.ktor:ktor-client-darwin:$ktor_version") + } + } + + jvmMain { + dependencies { + implementation("io.ktor:ktor-client-okhttp:$ktor_version") + } + } + } +} +``` + +## Usage + +Now you can use the `NetworkLoader` to load images from a URL. + +You can customize the behaviour of the request by passing in your own `HttpClient` +of `HttpRequestBuilder`: + +```kotlin +public class NetworkLoader( + private val httpClient: HttpClient = HttpClient(), + private val requestBuilder: HttpRequestBuilder = HttpRequestBuilder(), +) : ImageBitmapLoader +``` + +Now you can pass a `Url` object to load an image: + +```kotlin +@Composable +fun MyComposable(url: Url) { + val paletteState = rememberPaletteState(loader = NetworkLoader()) + LaunchedEffect(url) { + paletteState.generate(url) + } +} +``` + +The Image will be fetched, converted into a `ImageBitmap` then a palette will be generated. \ No newline at end of file diff --git a/extensions-resources/README.md b/extensions-resources/README.md new file mode 100644 index 0000000..192a109 --- /dev/null +++ b/extensions-resources/README.md @@ -0,0 +1,59 @@ +# Compose Multiplatform Resources Extensions + +This extension provides `ResourceLoader` a `ImageBitmapLoader` for images using Compose +Multiplatform Resources. + +| Library | Loader | Input Class | Demo | +|----------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------|------------| +| [`extensions-resources`](extensions-resources/README.md) | [Compose Multiplatform Resources](https://github.com/JetBrains/compose-multiplatform/tree/master/components/resources) | `ResourceLoader` | `Resource` | [`ResourcesPaletteScreen`](demo/composeApp/src/commonMain/kotlin/dev/jordond/kmpalette/palette/ResourcesPaletteScreen.kt) | + +## Setup + +Then you need to add the following to your `build.gradle.kts` file: + +```kotlin +kotlin { + sourceSets { + commonMain { + dependencies { + implementation(libs.kmpalette.core) + implementation(libs.kmpalette.extensions.resources) + @OptIn(org.jetbrains.compose.ExperimentalComposeLibrary::class) + implementation(compose.components.resources) + } + } + } +} + +// ... + +android { + // ... + + sourceSets["main"].apply { + res.srcDirs("src/androidMain/resources") + resources.srcDirs("src/commonMain/resources") + } + + // ... +} +``` + +**Warning:** Although Compose Resources supports XML and SVG vector images, this library does not. +It will +crash if you attempt to use a vector format. + +## Usage + +Add your images to the `commonMain/resources` folder. You can then load them using +the `ResourceLoader`: + +```kotlin +val imageBitmap: ImageBitmap = ResourceLoader.load(resource("example1.png")) + +// Or using one of the composeable functions +val paletteState = rememebrPaletteState(loader = ResourceLoader) +LaunchedEffect(base64Image) { + paletteState.generate(resource("example1.png")) +} +``` \ No newline at end of file