# BorderRenderer

> BorderRenderer provides rendering and caching logic for drawing borders inside a [DrawScope].

## API Reference

> Source set: Common

```kotlin
public class BorderRenderer constructor(private val onProvideGraphicsLayer: () -> GraphicsLayer)
```

BorderRenderer provides rendering and caching logic for drawing borders inside a `DrawScope`.

BorderRenderer provides the same border drawing that `androidx.compose.foundation.border` uses so
you can draw borders from any drawing context, such as a
`androidx.compose.ui.node.DrawModifierNode`. This can be useful when you need to render multiple
inset borders at once, or efficiently animate borders. For simple cases you can continue to use
`androidx.compose.foundation.border`.

Borders drawn with BorderRenderer are internal borders - they grow inwards as the border width
increases.

BorderRenderer contains caches to efficiently draw borders over time. As a result, make sure to:
- Reuse the same BorderRenderer instance each time you draw the border
- Use a separate instance for each border that is drawn at the same time. For example, if you
want to draw two borders, inset from each other, each border should have its own
BorderRenderer. See the samples for more information.

Drawing a border from inside a `androidx.compose.ui.node.DrawModifierNode`:

Drawing two borders inset from each other (using separate BorderRenderers):

#### Parameters

| | |
| --- | --- |
| onProvideGraphicsLayer | Provides a [GraphicsLayer](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/classes/GraphicsLayer/api.md) needed for rendering certain borders. This lambda will be invoked when needed, and may be invoked multiple times. As a result make sure to cache / return the same valid [GraphicsLayer](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/classes/GraphicsLayer/api.md) to avoid creating many layers. This [GraphicsLayer](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/classes/GraphicsLayer/api.md) should not be used by any other [BorderRenderer](https://composables.com/jetpack-compose/androidx.compose.foundation/foundation/classes/BorderRenderer/api.md) instances or drawing code at the same time. The caller is responsible for its lifecycle - make sure to call [androidx.compose.ui.graphics.GraphicsContext.releaseGraphicsLayer](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/interfaces/GraphicsContext/api.md) when you no longer need it (such as when a Modifier.Node using this is detached). If you release the layer, make sure to return a new valid [GraphicsLayer](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/classes/GraphicsLayer/api.md) when this is called again (if the node is re-attached later). See the samples for example usage. |

## Functions

### drawBorder

> Source set: Common

```kotlin
public fun drawBorder(
        drawScope: DrawScope,
        width: Dp,
        brush: Brush,
        outline: Outline,
    ): Unit
```

Draws a border defined by `outline`, with `width` and `brush`, into `drawScope`. The border
will be drawn using the size defined by `outline`, not `DrawScope.size`. Borders drawn are
internal borders (drawn within the bounding box, not outside), and grow inwards as `width`
increases.

To modify the drawn border you can use `DrawScope` transformation APIs such as `translate`,
just as for any other drawing commands.

To draw several different borders at the same time, use a separate [BorderRenderer](https://composables.com/jetpack-compose/androidx.compose.foundation/foundation/classes/BorderRenderer/api.md) for each
one.

#### Parameters

| | |
| --- | --- |
| drawScope | The [DrawScope](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/interfaces/DrawScope/api.md) to draw the border into. |
| width | The width of the border in [Dp](https://composables.com/jetpack-compose/androidx.compose.ui/ui-unit/classes/Dp/api.md). |
| brush | The [Brush](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/classes/Brush/api.md) to paint the border with. |
| outline | The [Outline](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/classes/Outline/api.md) of the border. |

## Code Examples

### BorderRendererSample

```kotlin
@Sampled
fun BorderRendererSample() {
    // Note: you may need to implement semantics here, depending on your use case.
    class SimpleBorderNode(var width: Dp, var brush: Brush, var shape: Shape) :
        Modifier.Node(), DrawModifierNode {
        // The GraphicsLayer is only created if the BorderRenderer needs one, and is released when
        // the node is detached.
        private var graphicsLayer: GraphicsLayer? = null

        // Keep the same BorderRenderer across draws so it can reuse its drawing resources.
        private val borderRenderer = BorderRenderer {
            graphicsLayer
                ?: requireGraphicsContext().createGraphicsLayer().also { graphicsLayer = it }
        }

        override fun ContentDrawScope.draw() {
            drawContent()
            borderRenderer.drawBorder(
                drawScope = this,
                width = width,
                brush = brush,
                outline = shape.createOutline(size, layoutDirection, this),
            )
        }

        override fun onDetach() {
            graphicsLayer?.let { requireGraphicsContext().releaseGraphicsLayer(it) }
            graphicsLayer = null
        }
    }
}
```

### BorderRendererMultipleBordersSample

```kotlin
@Sampled
fun BorderRendererMultipleBordersSample() {
    // Note: you may need to implement semantics here, depending on your use case.
    class DoubleBorderNode : Modifier.Node(), DrawModifierNode {
        private val borderWidth = 2.dp
        // 2.dp between the inner edge of the outer border and the outer edge of the inner border
        private val innerBorderInset = borderWidth + 2.dp
        private val outerBrush = SolidColor(Color.Black)
        private val innerBrush = Brush.linearGradient(listOf(Color.Magenta, Color.Cyan))
        private val shape = CutCornerShape(8.dp)

        // Each border needs its own GraphicsLayer, as both may be used in the same draw.
        private var outerGraphicsLayer: GraphicsLayer? = null
        private var innerGraphicsLayer: GraphicsLayer? = null

        // Use a separate BorderRenderer for each border, so that each one can reuse its own
        // drawing resources across draws.
        private val outerBorderRenderer = BorderRenderer {
            outerGraphicsLayer
                ?: requireGraphicsContext().createGraphicsLayer().also { outerGraphicsLayer = it }
        }
        private val innerBorderRenderer = BorderRenderer {
            innerGraphicsLayer
                ?: requireGraphicsContext().createGraphicsLayer().also { innerGraphicsLayer = it }
        }

        override fun ContentDrawScope.draw() {
            drawContent()
            val outerOutline = shape.createOutline(size, layoutDirection, this)
            // Draw the outer border at the edge
            outerBorderRenderer.drawBorder(
                drawScope = this,
                width = borderWidth,
                brush = outerBrush,
                outline = outerOutline,
            )
            val inset = innerBorderInset.toPx()
            // Draw the inner border inset from the outer border
            inset(inset) {
                // The size in this scope is already inset, so this outline will be smaller
                val innerOutline = shape.createOutline(size, layoutDirection, this)
                innerBorderRenderer.drawBorder(
                    drawScope = this,
                    width = borderWidth,
                    brush = innerBrush,
                    outline = innerOutline,
                )
            }
        }

        override fun onDetach() {
            outerGraphicsLayer?.let { requireGraphicsContext().releaseGraphicsLayer(it) }
            innerGraphicsLayer?.let { requireGraphicsContext().releaseGraphicsLayer(it) }
            outerGraphicsLayer = null
            innerGraphicsLayer = null
        }
    }
}
```
