Landscapist Documentation

Landscapist provides several architectural advantages for modern application development:

• Cross-Platform Support: LandscapistImage works identically across all Compose Multiplatform targets, allowing you to share image loading logic, caching configuration, and UI components without platform-specific conditional code.
• Pipeline Control: Unlike wrapper libraries, Landscapist exposes the entire image loading pipeline. You can configure network timeouts, cache policies, image transformations, and loading priorities at both global and per-request levels.
• Performance Optimizations:
  • Android: Uses two-pass inSampleSize for downsampling at decode time, hardware bitmaps for opaque images (API 26+), and an Okio-based disk cache with a byte-bounded LRU memory cache.
  • Efficiency: Concurrent loads of the same image are coalesced into a single fetch/decode operation. Memory cache can trim on system memory pressure via an Android memory-pressure handler.
• Plugin Ecosystem: Supports seamless integration with plugins for shimmer placeholders, crossfade animations, blur transformations, palette extraction, and zoomable images.

Landscapist provides direct access to its caching layers for manual management.

Memory Cache

Uses an LRU (Least Recently Used) policy. You can clear it, trim it to a specific size, or inspect its current usage.

Disk Cache

Provides persistent storage for offline access. You can clear the entire disk cache via landscapist.config.diskCache?.clear().

Cache Policies

Control caching behavior on a per-request basis using CachePolicy:

• CachePolicy.ENABLED: Read and write to both caches.
• CachePolicy.READ_ONLY: Only read from cache, never write.
• CachePolicy.WRITE_ONLY: Only write to cache, never read.
• CachePolicy.DISABLED: Disable caching completely.

// Memory Cache management
val memoryCache = landscapist.config.memoryCache
memoryCache?.clear()
memoryCache?.trimToSize(32 * 1024 * 1024L)

// Disk Cache management
val diskCache = landscapist.config.diskCache
diskCache?.clear()

// Per-request policy
val request = ImageRequest.builder()
    .model(url)
    .memoryCachePolicy(CachePolicy.ENABLED)
    .diskCachePolicy(CachePolicy.READ_ONLY)
    .build()

Landscapist uses a plugin-based architecture to manage image loading states and visual effects:

• ImageComponent: A container that holds a collection of ImagePlugin instances. It manages how different plugins are composed during the image lifecycle.
• ImagePlugin: An executable Compose interface triggered by specific image states. You can use built-in plugins or implement custom ones to tailor behavior.

Available Plugin Types

• PainterPlugin: Composes with a given Painter.
• LoadingStatePlugin: Executed while the state is ImageLoadState.Loading.
• SuccessStatePlugin: Executed when the state is ImageLoadState.Success.
• FailureStatePlugin: Executed when the state is ImageLoadState.Failure.

By combining these, you can define exactly what happens (e.g., showing a shimmer, a placeholder, or a specific transition) during each phase of the loading process.

// Example of a custom LoadingStatePlugin
data class LoadingPlugin(val source: Any?) : ImagePlugin.LoadingStatePlugin {
  @Composable
  override fun compose(
    modifier: Modifier,
    imageOptions: ImageOptions,
    executor: @Composable (IntSize) -> Unit,
  ): ImagePlugin = apply {
    if (source != null && imageOptions != null) {
      ImageBySource(
        source = source,
        modifier = modifier,
        alignment = imageOptions.alignment,
        contentDescription = imageOptions.contentDescription,
        contentScale = imageOptions.contentScale,
        colorFilter = imageOptions.colorFilter,
        alpha = imageOptions.alpha
      )
    }
  }
}

Landscapist uses a plugin system to handle image loading states. An ImagePlugin is a pluggable interface that provides specific logic for different states:

• PainterPlugin: Composes with a Painter.
• LoadingStatePlugin: Executed during ImageLoadState.Loading.
• SuccessStatePlugin: Executed during ImageLoadState.Success.
• FailureStatePlugin: Executed during ImageLoadState.Failure.

You can compose multiple plugins into an ImageComponent using rememberImageComponent and the add() method or the + operator.

data class LoadingPlugin(val source: Any?) : ImagePlugin.LoadingStatePlugin {

  @Composable
  override fun compose(
    modifier: Modifier,
    imageOptions: ImageOptions?
  ): ImagePlugin = apply {
    if (source != null && imageOptions != null) {
      ImageBySource(
        source = source,
        modifier = modifier,
        alignment = imageOptions.alignment,
        contentDescription = imageOptions.contentDescription,
        contentScale = imageOptions.contentScale,
        colorFilter = imageOptions.colorFilter,
        alpha = imageOptions.alpha
      )
    }
  }
}

// Using plugins with add()
GlideImage(
  imageModel = { poster.image },
  component = rememberImageComponent {
    add(CircularRevealPlugin())
    add(LoadingPlugin(source))
  },
)

// Using plugins with the + operator
GlideImage(
  imageModel = { poster.image },
  component = rememberImageComponent {
    +CircularRevealPlugin()
    +LoadingPlugin(source)
  },
)

You can animate a tapped thumbnail from ImageGallery into the ImageViewer using ImageSharedTransitionConfig.

Requirements:

1. Wrap both components in a SharedTransitionLayout (or use NavHost and provide the AnimatedContentScope).
2. Pass the exact same ImageSharedTransitionConfig instance to both ImageGallery and ImageViewer.
3. The sharedTransitionScope should be the scope provided by the SharedTransitionLayout or NavHost.
4. The animatedContentScope should be the scope provided by the AnimatedContent or composable destination.

SharedTransitionLayout {
  AnimatedContent(
    targetState = showViewer,
    transitionSpec = { fadeIn() togetherWith fadeOut() },
    label = "gallery-viewer",
  ) {\ viewerVisible ->
    val animatedContentScope = this
    if (!viewerVisible) {
      ImageGallery(
        images = imageUrls,
        onImageClick = { index, _ ->
          selectedPage = index
          showViewer = true
        },
        sharedTransition = ImageSharedTransitionConfig(
          sharedTransitionScope = this@SharedTransitionLayout,
          animatedContentScope = animatedContentScope,
        ),
      )
    } else {
      ImageViewer(
        images = imageUrls,
        state = rememberImageViewerState(
          initialPage = selectedPage,
          pageCount = { imageUrls.size },
        ),
        onDismiss = { showViewer = false },
        sharedTransition = ImageSharedTransitionConfig(
          sharedTransitionScope = this@SharedTransitionLayout,
          animatedContentScope = animatedContentScope,
        ),
      )
    }
  }
}