Conservazione dello stato e archiviazione permanente

La conservazione dello stato e l'archiviazione permanente sono aspetti non banali delle app di inchiostro digitale, soprattutto in Compose. Gli oggetti dati principali, come le proprietà del pennello e i punti che formano un tratto, sono complessi e non vengono salvati automaticamente. Ciò richiede una strategia deliberata per il salvataggio dello stato durante scenari come modifiche alla configurazione e salvataggio permanente dei disegni di un utente in un database.

Conservazione dello stato

In Jetpack Compose, lo stato dell'UI viene in genere gestito utilizzando remember e rememberSaveable. Sebbene rememberSaveable offra la conservazione automatica dello stato in caso di modifiche alla configurazione, le sue funzionalità integrate sono limitate a tipi di dati primitivi e oggetti che implementano Parcelable o Serializable.

Per gli oggetti personalizzati che contengono proprietà complesse, ad esempio Brush, devi definire meccanismi espliciti di serializzazione e deserializzazione utilizzando un salvataggio dello stato personalizzato. Definendo un Saver personalizzato per l'oggetto Brush, puoi conservare gli attributi essenziali del pennello quando si verificano modifiche alla configurazione, come mostrato nell'esempio brushStateSaver seguente.

fun brushStateSaver(converters: Converters): Saver<MutableState<Brush>, SerializedBrush> = Saver(
    save = { converters.serializeBrush(it.value) },
    restore = { mutableStateOf(converters.deserializeBrush(it)) },
)

Puoi quindi utilizzare il Saver personalizzato per mantenere lo stato del pennello selezionato:

val currentBrush = rememberSaveable(saver = brushStateSaver(Converters())) { mutableStateOf(defaultBrush) }

Archiviazione permanente

To enable features such as document saving, loading, and potential real-time collaboration, store strokes and associated data in a serialized format. For the Ink API, manual serialization and deserialization are necessary.

To accurately restore a stroke, save its Brush and StrokeInputBatch.

• Brush: Includes numeric fields (size, epsilon), color, and BrushFamily.
• StrokeInputBatch: A list of input points with numeric fields.

The Storage module simplifies compactly serializing the most complex part: the StrokeInputBatch.

Note: See data transfer objects such as SerializedBrush and SerializedStroke as well as the Converters helper class in the Data object and converter helpers section.

To save a stroke:

• Serialize the StrokeInputBatch using the storage module's encode function. Store the resulting binary data.
• Separately save the essential properties of the stroke's Brush:
  • The enum that represents the brush family &mdash Although the instance can be serialized, this is not efficient for apps that use a limited selection of brush families
  • colorLong
  • size
  • epsilon

fun serializeStroke(stroke: Stroke): SerializedStroke {
  val serializedBrush = serializeBrush(stroke.brush)
  val encodedSerializedInputs = ByteArrayOutputStream().use
    {
      stroke.inputs.encode(it)
      it.toByteArray()
    }

  return SerializedStroke(
    inputs = encodedSerializedInputs,
    brush = serializedBrush
  )
}

To load a stroke object:

• Retrieve the saved binary data for the StrokeInputBatch and deserialize it using the storage module's decode() function.
• Retrieve the saved Brush properties and create the brush.

• Create the final stroke using the recreated brush and the deserialized StrokeInputBatch.

  fun deserializeStroke(serializedStroke: SerializedStroke): Stroke {
    val inputs = ByteArrayInputStream(serializedStroke.inputs).use {
      StrokeInputBatch.decode(it)
    }
    val brush = deserializeBrush(serializedStroke.brush)
    return Stroke(brush = brush, inputs = inputs)
  }
  

Handle zoom, pan, and rotation

If your app supports zooming, panning, or rotation, you must provide the current transformation to InProgressStrokes. This helps newly drawn strokes match the position and scale of your existing strokes.

You do this by passing a Matrix to the pointerEventToWorldTransform parameter. The matrix should represent the inverse of the transformation you apply to your finished strokes canvas.

@Composable
fun ZoomableDrawingScreen(...) {
    // 1. Manage your zoom/pan state (e.g., using detectTransformGestures).
    var zoom by remember { mutableStateOf(1f) }
    var pan by remember { mutableStateOf(Offset.Zero) }

    // 2. Create the Matrix.
    val pointerEventToWorldTransform = remember(zoom, pan) {
        android.graphics.Matrix().apply {
            // Apply the inverse of your rendering transforms
            postTranslate(-pan.x, -pan.y)
            postScale(1 / zoom, 1 / zoom)
        }
    }

    Box(modifier = Modifier.fillMaxSize()) {
        // ...Your finished strokes Canvas, with regular transform applied

        // 3. Pass the matrix to InProgressStrokes.
        InProgressStrokes(
            modifier = Modifier.fillMaxSize(),
            pointerEventToWorldTransform = pointerEventToWorldTransform,
            defaultBrush = currentBrush,
            nextBrush = onGetNextBrush,
            onStrokesFinished = onStrokesFinished
        )
    }
}

Note: For details on implementing the gestures themselves, refer to the Jetpack Compose documentation for detectTransformGestures.

Export strokes

Potresti dover esportare la scena del tratto come file immagine statica. Questa funzionalità è utile per condividere il disegno con altre applicazioni, generare miniature o salvare una versione finale e non modificabile dei contenuti.

Per esportare una scena, puoi eseguire il rendering dei tratti in una bitmap off-screen anziché direttamente sullo schermo. Utilizza Android's Picture API, che ti consente di registrare disegni su una tela senza bisogno di un componente UI visibile.

La procedura prevede la creazione di un'istanza Picture, la chiamata di beginRecording() per ottenere un Canvas e l'utilizzo del CanvasStrokeRenderer esistente per disegnare ogni tratto su quel Canvas. Dopo aver registrato tutti i comandi di disegno, puoi utilizzare Picture per creare un Bitmap, che puoi comprimere e salvare in un file.

fun exportDocumentAsImage() {
  val picture = Picture()
  val canvas = picture.beginRecording(bitmapWidth, bitmapHeight)

  // The following is similar logic that you'd use in your custom View.onDraw or Compose Canvas.
  for (item in myDocument) {
    when (item) {
      is Stroke -> {
        canvasStrokeRenderer.draw(canvas, stroke, worldToScreenTransform)
      }
      // Draw your other types of items to the canvas.
    }
  }

  // Create a Bitmap from the Picture and write it to a file.
  val bitmap = Bitmap.createBitmap(picture)
  val outstream = FileOutputStream(filename)
  bitmap.compress(Bitmap.CompressFormat.PNG, 100, outstream)
}

Data object and converter helpers

Define a serialization object structure that mirrors needed Ink API objects.

Use the Ink API's storage module to encode and decode StrokeInputBatch.

Data transfer objects

@Parcelize
@Serializable
data class SerializedStroke(
  val inputs: ByteArray,
  val brush: SerializedBrush
) : Parcelable {
  override fun equals(other: Any?): Boolean {
    if (this === other) return true
    if (other !is SerializedStroke) return false
    if (!inputs.contentEquals(other.inputs)) return false
    if (brush != other.brush) return false
    return true
  }

  override fun hashCode(): Int {
    var result = inputs.contentHashCode()
    result = 31 * result + brush.hashCode()
    return result
  }
}

@Parcelize
@Serializable
data class SerializedBrush(
  val size: Float,
  val color: Long,
  val epsilon: Float,
  val stockBrush: SerializedStockBrush,
  val clientBrushFamilyId: String? = null
) : Parcelable

enum class SerializedStockBrush {
  Marker,
  PressurePen,
  Highlighter,
  DashedLine,
}

Converters

object Converters {
  private val stockBrushToEnumValues = mapOf(
    StockBrushes.marker() to SerializedStockBrush.Marker,
    StockBrushes.pressurePen() to SerializedStockBrush.PressurePen,
    StockBrushes.highlighter() to SerializedStockBrush.Highlighter,
    StockBrushes.dashedLine() to SerializedStockBrush.DashedLine,
  )

  private val enumToStockBrush =
    stockBrushToEnumValues.entries.associate { (key, value) -> value to key
  }

  private fun serializeBrush(brush: Brush): SerializedBrush {
    return SerializedBrush(
      size = brush.size,
      color = brush.colorLong,
      epsilon = brush.epsilon,
      stockBrush = stockBrushToEnumValues[brush.family] ?: SerializedStockBrush.Marker,
    )
  }

  fun serializeStroke(stroke: Stroke): SerializedStroke {
    val serializedBrush = serializeBrush(stroke.brush)
    val encodedSerializedInputs = ByteArrayOutputStream().use { outputStream ->
      stroke.inputs.encode(outputStream)
      outputStream.toByteArray()
    }

    return SerializedStroke(
      inputs = encodedSerializedInputs,
      brush = serializedBrush
    )
  }

  private fun deserializeStroke(
    serializedStroke: SerializedStroke,
  ): Stroke? {
    val inputs = ByteArrayInputStream(serializedStroke.inputs).use { inputStream ->
        StrokeInputBatch.decode(inputStream)
    }
    val brush = deserializeBrush(serializedStroke.brush, customBrushes)
    return Stroke(brush = brush, inputs = inputs)
  }

  private fun deserializeBrush(
    serializedBrush: SerializedBrush,
  ): Brush {
    val stockBrushFamily = enumToStockBrush[serializedBrush.stockBrush]
    val brushFamily = customBrush?.brushFamily ?: stockBrushFamily ?: StockBrushes.marker()

    return Brush.createWithColorLong(
      family = brushFamily,
      colorLong = serializedBrush.color,
      size = serializedBrush.size,
      epsilon = serializedBrush.epsilon,
    )
  }
}