<?php

namespace dynamicimages\interfaces;

use dynamicimages\classes\dynamicimages_asset;
use dynamicimages\helpers\dynamicimages_tool;

interface dynamicimages_image_i
{
    /**
     * Set the assets
     * @param dynamicimages_asset[] $assets The array of assets to set
     * @return self
     */
    public function setAssets(array $assets): self;
    /**
     * Get the assets
     * @return dynamicimages_asset[] The array of assets
     */
    public function getAssets(): array;
    /**
     * Add an asset
     * @param dynamicimages_asset $asset The asset to add
     * @return self
     */
    public function addAsset(dynamicimages_asset $asset): self;

    // ===== Canvas lifecycle (internal image property) =====
    /**
     * Initialize a blank Imagick canvas with the specified size.
     * Background can be 'transparent' or any valid color string.
     */
    public function initImageCanvas(int $width, int $height, string $background = 'transparent'): self;

    /**
     * Clear and destroy the current canvas, if any.
     */
    public function clearImage(): self;

    /**
     * Return current canvas size as [width => int, height => int].
     * Throws if canvas is not initialized.
     * @return array{width:int,height:int}
     */
    public function getCanvasSize(): array;

    // ===== Explicit asset compositing =====
    /**
     * Draw an asset onto the canvas at (x,y) with given opacity (0..1).
     * Requires the canvas to be initialized first via initImageCanvas().
     */
    public function drawAsset(dynamicimages_asset $asset, int $x, int $y, float $opacity = 1.0): self;

    // ===== Transformations on the temporary image object =====
    public function resize(int $width, int $height): self;
    public function crop(int $width, int $height, int $x, int $y): self;
    public function rotate(float $degrees, string $background = 'transparent'): self;
    /** Set global canvas opacity (0..1). */
    public function setOpacity(float $opacity): self;

    /**
     * Set tools to apply to the image
     * @param dynamicimages_tool[] $tools
     * @return self
     */
    public function setTools(array $tools): self;

    /**
     * Add a single tool to the list
     * @param dynamicimages_tool $tool
     * @return self
     */
    public function addTool(dynamicimages_tool $tool): self;

    /**
     * Get all tools assigned to this image
     * @return dynamicimages_tool[]
     */
    public function getTools(): array;

    /**
     * Export the composed image as base64 data URI
     * @param string|null $format Optional target format (e.g. 'png', 'jpeg')
     * @param int $quality Quality for lossy formats (0-100)
     * @return string base64 data URI string (e.g. data:image/png;base64,....)
     */
    public function exportAsBase64(?string $format = null, int $quality = 90): string;

    /**
     * Export the composed image as binary image data.
     * @param string|null $format Optional target format (e.g. 'png', 'jpeg')
     * @param int $quality Quality for lossy formats (0-100)
     * @return string binary image data
     */
    public function exportBinary(?string $format = null, int $quality = 90): string;

    /**
     * Directly serve the composed image to the client with proper headers.
     * Convenience wrapper for outputting binary image data.
     *
     * @param string|null $format Optional target format (e.g. 'png', 'jpeg')
     * @param int $quality Quality for lossy formats (0-100)
     */
    public function servePicture(?string $format = null, int $quality = 90): void;
}