/**
 * This object contains helper methods for generating an RGB [stretch visualization](https://developers.arcgis.com/javascript/latest/references/core/renderers/RasterStretchRenderer/) for raster layers (i.e. [ImageryLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/ImageryLayer/), [ImageryTileLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/ImageryTileLayer/), or [WCSLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/WCSLayer/)).
 *
 * The [createRenderer()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/raster/renderers/rgb/#createRenderer) method in this module generates a renderer that may be applied directly to the input layer.
 *
 * @since 4.20
 */
import type RasterStretchRenderer from "../../../renderers/RasterStretchRenderer.js";
import type { RasterStretchType } from "../../../renderers/support/raster/types.js";
import type { RasterRendererParameters } from "./types.js";

export interface RasterRGBRendererParameters extends RasterRendererParameters {
  /** A preferred stretch type can be provided. See [RasterStretchRenderer.stretchType](https://developers.arcgis.com/javascript/latest/references/core/renderers/RasterStretchRenderer/#stretchType) for more information. */
  stretchType?: RasterStretchType;
  /** The RGB band indexes following the order of red, green, and blue channels. This array must have three numbers. */
  rgbBandIds?: [
      number,
      number,
      number
  ];
  /**
   * The gamma values to be used if `useGamma` is `true`.
   *   Gamma refers to the degree of contrast between the mid-level gray values of a raster dataset.
   *   It does not affect black or white values, only the middle values.
   *   By applying a gamma correction, you can control the overall brightness of an [ImageryLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/ImageryLayer/).
   *   Gamma stretching is only valid when `stretchType` is `none`, `standard-deviation`, or `min-max`. See [RasterStretchRenderer.gamma](https://developers.arcgis.com/javascript/latest/references/core/renderers/RasterStretchRenderer/#gamma) for more information.
   */
  gamma?: [
      number,
      number,
      number
  ];
  /** Indicates whether the `gamma` values should be used. When `false`, the gamma is calculated from the statistics and histogram of the data. */
  useGamma?: boolean;
  /**
   * When `true`, calculates the renderer's statistics based on the current
   *   display extent and recalculates them as you zoom and pan around the image.
   */
  dynamicRangeAdjustment?: boolean;
  /**
   * Useful in scenarios where an image service does not have statistics. When `true`, this function estimates
   *   global statistics to keep a constant visual on pan and zoom, unlike `dynamicRangeAdjustment` which recalculates statistics on each extent change.
   */
  estimateStatistics?: boolean;
}

/**
 * The result object of the [createRenderer()](https://developers.arcgis.com/javascript/latest/references/core/smartMapping/raster/renderers/rgb/#createRenderer) method. See the table
 * below for details of each property.
 */
export interface RasterRGBResult {
  /**
   * The RGB RasterStretchRenderer renderer to apply
   *   to the input layer.
   */
  renderer: RasterStretchRenderer;
  /** The RGB band indexes following the order of red, green, and blue channels. */
  rgbBandIds?: [
      number,
      number,
      number
  ] | null;
}

/**
 * Generates an RGB [RasterStretchRenderer](https://developers.arcgis.com/javascript/latest/references/core/renderers/RasterStretchRenderer/) to render three selected bands into
 * red, green, and blue color channels.
 *
 * @param parameters - Input parameters for generating a RGB stretch visualization. The `colorRamp`, `gamma`, `useGamma`, and `dynamicRangeAdjustment` parameters are not related to RGB band ID selection or stretch type. Pass them in to preserve the existing settings if desired.
 * @returns Resolves to
 *   an object containing a stretch renderer that can be set on the input renderer.
 */
export function createRenderer(parameters: RasterRGBRendererParameters): Promise<RasterRGBResult>;