react-native-nitro-image-pipeline 1.4.0 → 1.5.0

package/README.md

@@ -71,6 +71,38 @@ so a style that already rounds the view rounds the bitmap too, with no separate
 other prop (`resizeMode`, `recyclingKey`, `testID`, …) is passed straight through to
 `NativeNitroImage`.
 
+### `<NativePipelineImage>` component
+
+The fully native-driven variant of `<PipelineImage>`, for when per-image JS work matters (long,
+fast-scrolling lists): after the first render there are **zero JS round trips per image**. The
+native view starts the request the moment it attaches to the window — at its own laid-out size,
+so nothing waits for an `onLayout` event to reach JS — and cancels it (releasing the bitmap) when
+it detaches, which makes off-screen list cells free. Re-attaching hits the shared memory cache,
+so recycled cells re-display instantly.
+
+```tsx
+import { NativePipelineImage } from 'react-native-nitro-image-pipeline';
+
+<NativePipelineImage
+  url="https://example.com/photo.jpg"
+  style={styles.photo} // size measured natively; borderRadius baked into the bitmap
+  blur={2} // points, like PipelineImage
+/>;
+```
+
+`blur`/`cornerRadius` are in points and `style`'s `borderRadius` is picked up automatically,
+exactly like `<PipelineImage>`. The trade-offs of going fully native:
+
+- No `onLoad`/`onError` — the loaded `Image` never crosses into JS. Use `<PipelineImage>` or
+  `useImage` when you need them.
+- The bitmap is loaded once at the size the view first has; if the view resizes later, the bitmap
+  scales with it instead of reloading.
+
+Under the hood this is `NitroImagePipeline.createImageLoader(url, options)` — an
+[`ImageLoader`](https://github.com/mrousavy/react-native-nitro-image) driven by
+`NativeNitroImage` — so you can also use the `usePipelineImageLoader(url, options)` hook directly
+with your own `<NativeNitroImage image={loader} />`.
+
 ### Animating with `react-native-reanimated`
 
 `<PipelineImage>` forwards its `ref` to the underlying `NativeNitroImage` host view, so it can be
@@ -241,6 +273,31 @@ Loads an image from a URL and returns a `Promise<Image>`.
 | `ref` | `Ref<PipelineImageRef>` | — | Forwarded to the underlying `NativeNitroImage` host view — gives access to native-view methods (`measure`, …) and makes the component work with `Animated.createAnimatedComponent` (see [Animating](#animating-with-react-native-reanimated)) |
 | `…NativeNitroImage props` | — | — | Everything else (`resizeMode`, `recyclingKey`, `testID`, …) is passed through to `NativeNitroImage` |
 
+### `<NativePipelineImage>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | — | Image URL to load |
+| `style` | `StyleProp<ViewStyle>` | — | Layout style. The native side measures the view and loads at that size; `borderRadius`-family properties drive `cornerRadius` when it's omitted |
+| `blur` | `number` | `0` | Gaussian blur strength, in **points** (screen scale applied natively) |
+| `cornerRadius` | `number \| CornerRadii` | derived from `style` | Corner radius, in **points** (screen scale applied natively) |
+| `cache` | `'memory' \| 'disk' \| 'none'` | platform default | Caching strategy |
+| `resize` | `{ width, height }` | measured from the view | Explicit target bitmap size in **pixels**, skipping the native measurement. Rarely needed |
+| `ref` | `Ref<NativePipelineImageRef>` | — | Forwarded to the underlying `NativeNitroImage` host view |
+| `…NativeNitroImage props` | — | — | Everything else (`resizeMode`, `recyclingKey`, `testID`, …) is passed through; `recyclingKey` defaults to `url` |
+
+No `onLoad`/`onError`: loading happens entirely natively and the result never crosses into JS.
+
+### `createImageLoader(url, options?)` / `usePipelineImageLoader(url, options?)`
+
+Creates the [`ImageLoader`](https://github.com/mrousavy/react-native-nitro-image) that powers
+`<NativePipelineImage>`, for use with your own `<NativeNitroImage image={loader} />`. The view
+calls into it natively when it attaches (load at the view's laid-out size) and detaches
+(cancel + release). `options` takes `blur`/`cornerRadius` in **points** and an optional
+pixel-based `resize` override — see the `ViewOptions` type. The hook memoizes by value, so
+inline options literals are fine. `loader.loadImage()` also works imperatively and resolves with
+the processed `Image`.
+
 ### `resizeForStyle(style)` / `resizeForLayout(width, height)`
 
 Converts a layout size in points to a bitmap `resize` option in pixels. Returns
@@ -300,11 +357,12 @@ Two things follow from the unit being *source* pixels:
 Values below ~1 are smaller than the smallest kernel either backend can build and are effectively a
 no-op. There is no upper bound.
 
-Implementation: iOS runs three Accelerate box-convolution passes sized to hit the requested sigma
-(the standard three-box Gaussian approximation, accurate to a few percent); Android uses
-RenderScript's true Gaussian, downscaling first when sigma exceeds the single-pass ceiling of
-~10.6px and compensating the radius so the result is unchanged. Both clamp at the edges, so blurred
-images keep their borders instead of fading out.
+Implementation: both platforms run the same three box-convolution passes sized to hit the requested
+sigma (the standard three-box Gaussian approximation, accurate to a few percent) — iOS through
+Accelerate's `vImageBoxConvolve_ARGB8888`, Android through a C++ port of that kernel working directly
+on the bitmap's pixels. The two are checked against each other on every CI run and produce
+byte-identical output for the same input. Both clamp at the edges, so blurred images keep their
+borders instead of fading out.
 
 ### `setMemoryCacheLimit(bytes)`
 
@@ -332,6 +390,15 @@ The pipeline is set up so RAM scales with what you display, not with what you do
   size known, both platforms decode the source *near that size* instead of at full resolution —
   iOS via a downsampled thumbnail decode, Android via Coil's subsampling. Without `resize`, a
   48 MP photo decompresses to ~190 MB of bitmap no matter how small you display it.
+- **Android draws transformed images from hardware bitmaps** (API 26+). When a view loads its
+  image natively (`<NativePipelineImage>`, or `<NativeNitroImage image={createImageLoader(...)}>`),
+  a resized, blurred or rounded result is uploaded to a `Bitmap.Config.HARDWARE` bitmap once and
+  cached like that, so its pixels live in GPU memory instead of the native heap and each view
+  drawing it skips a texture upload. In a 200-cell list of rounded thumbnails this cut the app's
+  PSS by ~100 MB on a Pixel 6a. Images returned to JavaScript — `loadImage` and
+  `createImageLoader(...).loadImage()` — skip that step, so their transformed results stay
+  software bitmaps with readable pixels (`toArrayBuffer`/`toBase64`); the two paths cache under
+  different keys only when that upload step is present.
 - **Prefetching stores bytes, not bitmaps.** `preLoadImage(s)` writes the download to the disk
   cache and skips decoding entirely.
 - **The in-memory cache is capped and tunable** (defaults: 128 MB on iOS, 25% of the app's memory

package/android/CMakeLists.txt

@@ -11,6 +11,8 @@ add_compile_options(-DRN_SERIALIZABLE_STATE=1)
 # Define C++ library and add all sources
 add_library(${PACKAGE_NAME} SHARED
         src/main/cpp/cpp-adapter.cpp
+        src/main/cpp/GaussianBlur.cpp
+        src/main/cpp/GaussianBlurJni.cpp
 )
 
 # Add Nitrogen specs :)
@@ -23,12 +25,14 @@ include_directories(
 )
 
 find_library(LOG_LIB log)
+find_library(JNIGRAPHICS_LIB jnigraphics)             # <-- AndroidBitmap_lockPixels for the blur
 find_package(react-native-nitro-image REQUIRED)   # <-- for the HybridImage type
 
 # Link all libraries together
 target_link_libraries(
         ${PACKAGE_NAME}
         ${LOG_LIB}
+        ${JNIGRAPHICS_LIB}
         android                                   # <-- Android core
         react-native-nitro-image::NitroImage      # <-- NitroImage
 )

package/android/src/main/cpp/GaussianBlur.cpp

@@ -0,0 +1,165 @@
+//
+//  GaussianBlur.cpp
+//  NitroImagePipeline
+//
+//  See GaussianBlur.hpp. Three box-blur passes approximate the Gaussian;
+//  each pass is a separable 2D box (horizontal running sum, then vertical
+//  running sum) that rounds to 8 bits only once, so it matches vImage's
+//  single 2D `vImageBoxConvolve_ARGB8888` pass on iOS rather than
+//  accumulating an extra rounding error per direction.
+//
+
+#include "GaussianBlur.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <cstring>
+#include <vector>
+
+namespace {
+
+constexpr int kChannels = 4;
+
+/// The standard deviation three box blurs of the given widths add up to.
+double standardDeviation(const uint32_t boxes[NITRO_BLUR_PASSES]) {
+  double sum = 0;
+  for (int i = 0; i < NITRO_BLUR_PASSES; i++) {
+    const double width = boxes[i];
+    sum += width * width - 1;
+  }
+  return std::sqrt(sum / 12);
+}
+
+/// One box pass of width `box` over the whole image, in place.
+///
+/// `rowSums` caches the horizontal running sums of the rows the vertical
+/// window currently covers (a ring of `ring` rows), so each row's horizontal
+/// pass runs once. The image edges are clamped: sampling outside the image
+/// returns the nearest border pixel, exactly like vImage's kvImageEdgeExtend.
+void boxPass(
+    uint8_t* pixels,
+    uint32_t width,
+    uint32_t height,
+    size_t stride,
+    uint32_t box,
+    std::vector<uint32_t>& rowSums,
+    std::vector<int64_t>& rowIndex,
+    std::vector<uint64_t>& column) {
+  const int64_t radius = (static_cast<int64_t>(box) - 1) / 2;
+  const int64_t w = width;
+  const int64_t h = height;
+  const size_t rowLength = static_cast<size_t>(width) * kChannels;
+  const int64_t ring = std::min<int64_t>(box, h) + 1;
+  const uint64_t area = static_cast<uint64_t>(box) * box;
+  const uint64_t half = area / 2;
+
+  std::fill(rowIndex.begin(), rowIndex.end(), -1);
+
+  auto clampRow = [h](int64_t y) { return std::max<int64_t>(0, std::min(h - 1, y)); };
+
+  // Horizontal running sum of image row `y` into the ring slot for it.
+  auto horizontal = [&](int64_t y) -> const uint32_t* {
+    const int64_t slot = y % ring;
+    uint32_t* out = rowSums.data() + static_cast<size_t>(slot) * rowLength;
+    if (rowIndex[static_cast<size_t>(slot)] == y) return out;
+    rowIndex[static_cast<size_t>(slot)] = y;
+
+    const uint8_t* row = pixels + static_cast<size_t>(y) * stride;
+    auto px = [&](int64_t x) {
+      return row + static_cast<size_t>(std::max<int64_t>(0, std::min(w - 1, x))) * kChannels;
+    };
+    uint32_t sum[kChannels] = {0, 0, 0, 0};
+    for (int64_t dx = -radius; dx <= radius; dx++) {
+      const uint8_t* p = px(dx);
+      for (int c = 0; c < kChannels; c++) sum[c] += p[c];
+    }
+    for (int64_t x = 0; x < w; x++) {
+      for (int c = 0; c < kChannels; c++) out[x * kChannels + c] = sum[c];
+      const uint8_t* leaving = px(x - radius);
+      const uint8_t* entering = px(x + radius + 1);
+      for (int c = 0; c < kChannels; c++) sum[c] += entering[c] - leaving[c];
+    }
+    return out;
+  };
+
+  // Vertical running sum over the clamped window [y - radius, y + radius].
+  std::fill(column.begin(), column.end(), 0);
+  for (int64_t dy = -radius; dy <= radius; dy++) {
+    const uint32_t* r = horizontal(clampRow(dy));
+    for (size_t i = 0; i < rowLength; i++) column[i] += r[i];
+  }
+
+  for (int64_t y = 0; y < h; y++) {
+    uint8_t* out = pixels + static_cast<size_t>(y) * stride;
+    for (size_t i = 0; i < rowLength; i++) {
+      out[i] = static_cast<uint8_t>((column[i] + half) / area);
+    }
+    if (y + 1 == h) break;
+    // The row leaving the window is still cached: it is inside the window,
+    // and the ring holds one row more than the window can span.
+    const uint32_t* leaving = horizontal(clampRow(y - radius));
+    const uint32_t* entering = horizontal(clampRow(y + radius + 1));
+    // Two steps: a uint32 `entering - leaving` would wrap before it reached
+    // the 64-bit accumulator.
+    for (size_t i = 0; i < rowLength; i++) column[i] += entering[i];
+    for (size_t i = 0; i < rowLength; i++) column[i] -= leaving[i];
+  }
+}
+
+}  // namespace
+
+extern "C" void nitro_blur_box_sizes(double sigma, uint32_t boxes[NITRO_BLUR_PASSES]) {
+  // Three boxes of widths w1…w3 produce a standard deviation of
+  // sqrt((w1² + w2² + w3² - 3) / 12). Box widths have to be odd, so the
+  // passes are split between the two odd integers straddling the ideal width
+  // and the split landing closest to `sigma` wins — the same search as
+  // `GaussianBlur.boxSizes(forSigma:)` on iOS, so both platforms pick the
+  // same widths.
+  const int passes = NITRO_BLUR_PASSES;
+  // A NaN or infinite sigma would make every candidate's error NaN and
+  // leave `boxes` unwritten; treat it, and sigma <= 0, as "no blur".
+  if (!std::isfinite(sigma) || sigma <= 0) {
+    for (int i = 0; i < passes; i++) boxes[i] = 1;
+    return;
+  }
+  int64_t lower = static_cast<int64_t>(std::sqrt((12 * sigma * sigma / passes) + 1));
+  if (lower % 2 == 0) lower -= 1;
+  lower = std::min<int64_t>(std::max<int64_t>(lower, 1), static_cast<int64_t>(UINT32_MAX) - 2);
+  const int64_t upper = lower + 2;
+
+  double bestError = INFINITY;
+  for (int lowerCount = 0; lowerCount <= passes; lowerCount++) {
+    uint32_t candidate[NITRO_BLUR_PASSES];
+    for (int pass = 0; pass < passes; pass++) {
+      candidate[pass] = static_cast<uint32_t>(pass < lowerCount ? lower : upper);
+    }
+    const double error = std::fabs(standardDeviation(candidate) - sigma);
+    if (error < bestError) {
+      bestError = error;
+      std::memcpy(boxes, candidate, sizeof(candidate));
+    }
+  }
+}
+
+extern "C" int nitro_blur_premultiplied_8888(
+    uint8_t* pixels, uint32_t width, uint32_t height, size_t stride, double sigma) {
+  if (width == 0 || height == 0) return 0;
+  uint32_t boxes[NITRO_BLUR_PASSES];
+  nitro_blur_box_sizes(sigma, boxes);
+
+  // Size the scratch buffers for the widest pass so every pass fits in them.
+  const uint32_t widest = *std::max_element(boxes, boxes + NITRO_BLUR_PASSES);
+  const size_t rowLength = static_cast<size_t>(width) * kChannels;
+  const size_t ring = std::min<size_t>(widest, height) + 1;
+  try {
+    std::vector<uint32_t> rowSums(ring * rowLength);
+    std::vector<int64_t> rowIndex(ring);
+    std::vector<uint64_t> column(rowLength);
+    for (int i = 0; i < NITRO_BLUR_PASSES; i++) {
+      boxPass(pixels, width, height, stride, boxes[i], rowSums, rowIndex, column);
+    }
+  } catch (const std::bad_alloc&) {
+    return -1;
+  }
+  return 0;
+}

package/android/src/main/cpp/GaussianBlur.hpp

@@ -0,0 +1,52 @@
+//
+//  GaussianBlur.hpp
+//  NitroImagePipeline
+//
+//  Cross-platform Gaussian blur — the Android kernel, a port of
+//  ios/GaussianBlur.swift.
+//
+//  This file deliberately depends on nothing but the C and C++ standard
+//  libraries (no JNI, no Android headers) so `scripts/verify-blur.swift` can
+//  compile it on the host and measure it against the iOS kernel. The JNI
+//  glue lives in GaussianBlurJni.cpp.
+//
+//  `sigma` is the standard deviation of the Gaussian, measured in *source
+//  image pixels* — the same sigma applied to the same source file produces
+//  the same result on iOS and Android. See the Swift file for why it is a
+//  sigma and not a "radius".
+//
+
+#pragma once
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Number of box-blur passes; both platforms run three.
+#define NITRO_BLUR_PASSES 3
+
+/// Widths for the three box-blur passes that approximate a Gaussian of
+/// `sigma` — the same numbers `GaussianBlur.boxSizes(forSigma:)` returns on
+/// iOS. Every width is odd and at least 1.
+void nitro_blur_box_sizes(double sigma, uint32_t boxes[NITRO_BLUR_PASSES]);
+
+/// Blurs `pixels` in place with the box widths for `sigma`.
+///
+/// The buffer is `height` rows of `width` 4-byte pixels, rows `stride` bytes
+/// apart. All four channels are convolved identically, so the byte order
+/// (ARGB on iOS, RGBA on Android) does not matter — but alpha must be
+/// premultiplied, otherwise transparent edges bleed dark halos into the blur.
+/// The image edges are clamped (each border pixel extends outward), matching
+/// vImage's kvImageEdgeExtend, so blurred images keep their borders instead
+/// of fading out into transparent black.
+///
+/// Returns 0 on success, or -1 if the scratch memory could not be allocated.
+int nitro_blur_premultiplied_8888(
+    uint8_t* pixels, uint32_t width, uint32_t height, size_t stride, double sigma);
+
+#ifdef __cplusplus
+}
+#endif

package/android/src/main/cpp/GaussianBlurJni.cpp

@@ -0,0 +1,50 @@
+//
+//  GaussianBlurJni.cpp
+//  NitroImagePipeline
+//
+//  JNI entry point for the blur kernel, called from
+//  transform/BlurTransformation.kt with a mutable ARGB_8888 bitmap.
+//
+
+#include <android/bitmap.h>
+#include <android/log.h>
+#include <jni.h>
+
+#include "GaussianBlur.hpp"
+
+namespace {
+constexpr const char* kTag = "NitroImagePipeline";
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_margelo_nitro_nitroimagepipeline_transform_BlurTransformation_nativeBlur(
+    JNIEnv* env, jclass, jobject bitmap, jfloat sigma) {
+  AndroidBitmapInfo info;
+  if (AndroidBitmap_getInfo(env, bitmap, &info) != ANDROID_BITMAP_RESULT_SUCCESS) {
+    __android_log_print(ANDROID_LOG_ERROR, kTag, "blur: AndroidBitmap_getInfo failed");
+    return JNI_FALSE;
+  }
+  if (info.format != ANDROID_BITMAP_FORMAT_RGBA_8888) {
+    __android_log_print(
+        ANDROID_LOG_ERROR,
+        kTag,
+        "blur: expected an ARGB_8888 bitmap (RGBA_8888 to the NDK), got NDK format %d",
+        info.format);
+    return JNI_FALSE;
+  }
+
+  void* pixels = nullptr;
+  if (AndroidBitmap_lockPixels(env, bitmap, &pixels) != ANDROID_BITMAP_RESULT_SUCCESS ||
+      pixels == nullptr) {
+    __android_log_print(ANDROID_LOG_ERROR, kTag, "blur: AndroidBitmap_lockPixels failed");
+    return JNI_FALSE;
+  }
+  const int result = nitro_blur_premultiplied_8888(
+      static_cast<uint8_t*>(pixels), info.width, info.height, info.stride, sigma);
+  AndroidBitmap_unlockPixels(env, bitmap);
+  if (result != 0) {
+    __android_log_print(ANDROID_LOG_ERROR, kTag, "blur: out of memory for the scratch buffers");
+    return JNI_FALSE;
+  }
+  return JNI_TRUE;
+}

package/android/src/main/java/com/margelo/nitro/nitroimagepipeline/HybridNitroImagePipeline.kt

@@ -1,6 +1,7 @@
 package com.margelo.nitro.nitroimagepipeline
 
 import android.content.Context
+import android.graphics.Bitmap
 import androidx.core.graphics.drawable.toBitmap
 import coil3.BitmapImage
 import coil3.ColorImage
@@ -26,12 +27,15 @@ import com.margelo.nitro.core.Promise
 import com.margelo.nitro.image.HybridImage
 import com.margelo.nitro.image.HybridImageSpec
 import com.margelo.nitro.nitroimagepipeline.transform.BlurTransformation
+import com.margelo.nitro.nitroimagepipeline.transform.HardwareBitmapTransformation
 import com.margelo.nitro.nitroimagepipeline.transform.ResizeTransformation
 import kotlin.math.roundToInt
+import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.async
 import kotlinx.coroutines.awaitAll
 import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 import okhttp3.OkHttpClient
 import okio.Path.Companion.toOkioPath
@@ -44,82 +48,27 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
   private val imageLoader: ImageLoader
     get() = getOrCreateImageLoader(context)
 
-  override fun loadImage(url: String, options: Options?): Promise<HybridImageSpec> = Promise.async {
-    val blur = options?.blur?.toFloat() ?: 0f
-    val resize =
-        options?.resize?.let { r ->
-          val width = r.width.roundToInt()
-          val height = r.height.roundToInt()
-          if (width > 0 && height > 0) width to height else null
-        }
-    val transformations = buildList {
-      // Resize first: blur sigma and corner radii are in pixels of the bitmap
-      // they run on, so they must see the final size.
-      resize?.let { (width, height) -> add(ResizeTransformation(width, height)) }
-      if (blur > 0f) add(BlurTransformation(context, blur))
-      options
-          ?.cornerRadius
-          ?.match(
-              first = { radius ->
-                if (radius > 0.0) add(RoundedCornersTransformation(radius.toFloat()))
-              },
-              second = { radii ->
-                // RoundedCornersTransformation rejects negative radii; treat them as square.
-                val topLeft = (radii.topLeft?.toFloat() ?: 0f).coerceAtLeast(0f)
-                val topRight = (radii.topRight?.toFloat() ?: 0f).coerceAtLeast(0f)
-                val bottomLeft = (radii.bottomLeft?.toFloat() ?: 0f).coerceAtLeast(0f)
-                val bottomRight = (radii.bottomRight?.toFloat() ?: 0f).coerceAtLeast(0f)
-                if (topLeft > 0f || topRight > 0f || bottomLeft > 0f || bottomRight > 0f) {
-                  add(RoundedCornersTransformation(topLeft, topRight, bottomLeft, bottomRight))
-                }
-              },
-          )
-    }
-    val request =
-        ImageRequest.Builder(context)
-            .data(url)
-            .apply {
-              when (options?.cache) {
-                CacheOption.MEMORY -> {
-                  memoryCachePolicy(CachePolicy.ENABLED)
-                  diskCachePolicy(CachePolicy.DISABLED)
-                }
-                CacheOption.DISK -> {
-                  memoryCachePolicy(CachePolicy.DISABLED)
-                  diskCachePolicy(CachePolicy.ENABLED)
-                }
-                CacheOption.NONE -> {
-                  memoryCachePolicy(CachePolicy.DISABLED)
-                  diskCachePolicy(CachePolicy.DISABLED)
-                }
-                null -> Unit // Coil defaults: both enabled
-              }
-              // Ask the decoder for the target size so a large source is
-              // subsampled near it instead of decoded at full resolution;
-              // ResizeTransformation then makes the size exact.
-              resize?.let { (width, height) ->
-                size(width, height)
-                scale(Scale.FILL)
-              }
-            }
-            .allowHardware(true)
-            .transformations(transformations)
-            .build()
+  init {
+    // Build the shared loader now, on a background thread, instead of on
+    // whichever thread the first request happens to run on. Creating it
+    // builds a CronetEngine, an OkHttpClient and the disk cache — well over
+    // a frame's worth of work — and the first `PipelineImageLoader` request
+    // would otherwise do that on the main thread.
+    (NitroModules.applicationContext as? Context)?.let { warmUpImageLoader(it) }
+  }
 
-    when (val result = imageLoader.execute(request)) {
+  override fun loadImage(url: String, options: Options?): Promise<HybridImageSpec> = Promise.async {
+    when (val result = imageLoader.execute(buildRequest(context, url, options))) {
       is ErrorResult -> throw result.throwable
-      is SuccessResult -> {
-        val bitmap =
-            when (val img = result.image) {
-              is BitmapImage -> img.bitmap
-              is DrawableImage -> img.drawable.toBitmap()
-              else -> throw Error("Unsupported image type: ${img.javaClass.simpleName}")
-            }
-        HybridImage(bitmap)
-      }
+      is SuccessResult -> HybridImage(bitmapOf(result))
     }
   }
 
+  override fun createImageLoader(
+      url: String,
+      options: ViewOptions?,
+  ): com.margelo.nitro.image.HybridImageLoaderSpec = PipelineImageLoader(context, url, options)
+
   // Preloading warms the disk cache only: the memory cache is skipped and the
   // decode step is replaced with a no-op (Coil's documented preload pattern),
   // so prefetching N URLs costs network + disk I/O instead of N full-resolution
@@ -151,8 +100,7 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
         if (sigma <= 0f) {
           hybridImage
         } else {
-          val blurred =
-              BlurTransformation(context, sigma).transform(hybridImage.bitmap, Size.ORIGINAL)
+          val blurred = BlurTransformation(sigma).transform(hybridImage.bitmap, Size.ORIGINAL)
           HybridImage(blurred)
         }
       }
@@ -182,12 +130,131 @@ class HybridNitroImagePipeline : HybridNitroImagePipelineSpec() {
     // must be shared across all HybridNitroImagePipeline instances.
     @Volatile private var sharedImageLoader: ImageLoader? = null
 
-    private fun getOrCreateImageLoader(context: Context): ImageLoader =
+    /**
+     * The [ImageRequest] for [url] with [options] applied — shared by [loadImage] and
+     * [PipelineImageLoader] so both hit the same caches with identical cache keys.
+     *
+     * With [hardwareResult], a transformed result is converted to a hardware bitmap before it is
+     * cached (see [HardwareBitmapTransformation]). Only for callers that draw the result: its
+     * pixels cannot be read back, and its cache key differs from the software one.
+     */
+    internal fun buildRequest(
+        context: Context,
+        url: String,
+        options: Options?,
+        hardwareResult: Boolean = false,
+    ): ImageRequest {
+      val blur = options?.blur?.toFloat() ?: 0f
+      val resize =
+          options?.resize?.let { r ->
+            val width = r.width.roundToInt()
+            val height = r.height.roundToInt()
+            if (width > 0 && height > 0) width to height else null
+          }
+      val roundedCorners: RoundedCornersTransformation? =
+          options
+              ?.cornerRadius
+              ?.match(
+                  first = { radius ->
+                    if (radius > 0.0) RoundedCornersTransformation(radius.toFloat()) else null
+                  },
+                  second = { radii ->
+                    // RoundedCornersTransformation rejects negative radii; treat them as square.
+                    val topLeft = (radii.topLeft?.toFloat() ?: 0f).coerceAtLeast(0f)
+                    val topRight = (radii.topRight?.toFloat() ?: 0f).coerceAtLeast(0f)
+                    val bottomLeft = (radii.bottomLeft?.toFloat() ?: 0f).coerceAtLeast(0f)
+                    val bottomRight = (radii.bottomRight?.toFloat() ?: 0f).coerceAtLeast(0f)
+                    if (topLeft > 0f || topRight > 0f || bottomLeft > 0f || bottomRight > 0f) {
+                      RoundedCornersTransformation(topLeft, topRight, bottomLeft, bottomRight)
+                    } else {
+                      null
+                    }
+                  },
+              )
+      val transformations = buildList {
+        // Resize first: blur sigma and corner radii are in pixels of the bitmap
+        // they run on, so they must see the final size. Coil's
+        // RoundedCornersTransformation already scale-fills and center-crops
+        // to the request size (`resize`, when set) as part of its own draw,
+        // so with rounded corners and no blur the explicit resize would only
+        // add an intermediate bitmap — and the radii still apply to the final
+        // size, because that is the size its output has.
+        if (resize != null && (blur > 0f || roundedCorners == null)) {
+          add(ResizeTransformation(resize.first, resize.second))
+        }
+        if (blur > 0f) add(BlurTransformation(blur))
+        roundedCorners?.let { add(it) }
+        // Without transformations Coil decodes straight to a hardware bitmap
+        // already (allowHardware below); only a transformed result needs the
+        // explicit upload.
+        if (hardwareResult && isNotEmpty() && HardwareBitmapTransformation.isSupported) {
+          add(HardwareBitmapTransformation.instance)
+        }
+      }
+      return ImageRequest.Builder(context)
+          .data(url)
+          .apply {
+            when (options?.cache) {
+              CacheOption.MEMORY -> {
+                memoryCachePolicy(CachePolicy.ENABLED)
+                diskCachePolicy(CachePolicy.DISABLED)
+              }
+              CacheOption.DISK -> {
+                memoryCachePolicy(CachePolicy.DISABLED)
+                diskCachePolicy(CachePolicy.ENABLED)
+              }
+              CacheOption.NONE -> {
+                memoryCachePolicy(CachePolicy.DISABLED)
+                diskCachePolicy(CachePolicy.DISABLED)
+              }
+              null -> Unit // Coil defaults: both enabled
+            }
+            // Ask the decoder for the target size so a large source is
+            // subsampled near it instead of decoded at full resolution;
+            // ResizeTransformation then makes the size exact.
+            resize?.let { (width, height) ->
+              size(width, height)
+              scale(Scale.FILL)
+            }
+          }
+          .allowHardware(true)
+          .transformations(transformations)
+          .build()
+    }
+
+    /** The decoded bitmap of a successful load. */
+    internal fun bitmapOf(result: SuccessResult): Bitmap =
+        when (val img = result.image) {
+          is BitmapImage -> img.bitmap
+          is DrawableImage -> img.drawable.toBitmap()
+          else -> throw Error("Unsupported image type: ${img.javaClass.simpleName}")
+        }
+
+    internal fun getOrCreateImageLoader(context: Context): ImageLoader =
         sharedImageLoader
             ?: synchronized(this) {
               sharedImageLoader ?: createImageLoader(context).also { sharedImageLoader = it }
             }
 
+    /**
+     * The shared loader, creating it on [Dispatchers.IO] if it doesn't exist yet. Use this from
+     * main-thread coroutines: once the loader exists this returns synchronously (so memory-cache
+     * hits stay synchronous), and until then the expensive creation runs off the main thread.
+     */
+    internal suspend fun awaitImageLoader(context: Context): ImageLoader =
+        sharedImageLoader ?: withContext(Dispatchers.IO) { getOrCreateImageLoader(context) }
+
+    /** Starts creating the shared loader on a background thread, if it doesn't exist yet. */
+    private fun warmUpImageLoader(context: Context) {
+      if (sharedImageLoader != null) return
+      CoroutineScope(Dispatchers.IO).launch {
+        // Warm-up only: an uncaught exception here would take the process
+        // down. If creation fails, `sharedImageLoader` stays null and the
+        // next request retries it and surfaces the error itself.
+        runCatching { getOrCreateImageLoader(context) }
+      }
+    }
+
     private fun createImageLoader(context: Context): ImageLoader {
       val okHttpClient =
           OkHttpClient.Builder()