react-native-nitro-image-pipeline 1.3.2 → 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,26 @@ 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)`
+
+Caps the in-memory cache of decoded bitmaps at `bytes`, evicting least-recently-used entries
+immediately if the cache is currently larger. Pass `0` to disable in-memory caching entirely — the
+disk cache keeps working. Synchronous; throws on negative or non-finite values.
+
+```ts
+// Keep at most 32 MB of decoded bitmaps in RAM
+NitroImagePipeline.setMemoryCacheLimit(32 * 1024 * 1024);
+
+// Or opt out of decoded-bitmap caching altogether
+NitroImagePipeline.setMemoryCacheLimit(0);
+```
 
 ### `clearCache()`
 
@@ -318,14 +390,34 @@ 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** (128 MB on iOS, 25% of the app's memory class on Android),
-  holds decoded bitmaps for instant re-display, and evicts least-recently-used entries — also in
-  response to memory warnings and backgrounding. Memory profilers attribute this cache to the app;
-  a plateau at the cap is expected and evictable, not a leak. Use `cache: 'disk'` or
-  `cache: 'none'` on images you know you won't show again soon, and `clearCache()` to drop
-  everything.
+- **The in-memory cache is capped and tunable** (defaults: 128 MB on iOS, 25% of the app's memory
+  class on Android). It holds decoded bitmaps for instant re-display and evicts
+  least-recently-used entries — also in response to memory warnings and backgrounding. Memory
+  profilers attribute this cache to the app; a plateau at the cap is expected and evictable, not a
+  leak. Lower the cap with [`setMemoryCacheLimit`](#setmemorycachelimitbytes), use `cache: 'disk'`
+  or `cache: 'none'` on images you won't show again soon, and `clearCache()` to drop everything.
+- **Coming from a setup with no decoded-image cache** (e.g. loading files you downloaded
+  yourself)? Steady-state RAM will read higher here *by design*: after screens unmount, the cache
+  keeps their bitmaps around for instant re-display. For the old memory profile with the
+  pipeline's features intact, pass `cache: 'disk'` on your requests or call
+  `setMemoryCacheLimit(0)` once — RAM then holds only the images currently referenced, and
+  re-displays decode from the disk cache (cheap, since decodes are subsampled to the target size).
+- **Android + `Image.dispose()`:** only call `dispose()` on images loaded with `cache: 'disk'` /
+  `cache: 'none'` (or with the memory cache disabled). With the memory cache on, the returned
+  image shares its bitmap with the cache, and disposing recycles a bitmap the cache may serve
+  again. Without `dispose()`, images are freed by the JS garbage collector — their bitmap size is
+  reported to it, so unreferenced images do get collected under pressure.
 
 ## Upgrading from 0.3.x
 

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;
+}