001/*******************************************************************************
002 * Copyright (c) 2024, 2026, Olivier Ayache.  All rights reserved.
003 *
004 * This file is part of AVPKit.
005 *
006 * AVPKit is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU Lesser General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * AVPKit is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with AVPKit.  If not, see <http://www.gnu.org/licenses/>.
018 *******************************************************************************/
019
020package com.avpkit.core.video;
021
022import java.awt.image.BufferedImage;
023import com.avpkit.core.IVideoPicture;
024import com.avpkit.core.IPixelFormat;
025
026/** This interface describes a converter which can perform bidirectional
027 * translation between a given {@link IVideoPicture} type and a {@link
028 * BufferedImage} type.  Converters are created by {@link
029 * ConverterFactory}.  Each converter can translate between any
030 * supported {@link com.avpkit.core.IPixelFormat.Type} and a single
031 * {@link BufferedImage} type.  Converters can optionally resize images
032 * during
033 * the conversion process.
034 */
035
036public interface IConverter
037{
038  /** Get the picture type, as defined by {@link
039   * com.avpkit.core.IPixelFormat.Type}, which this converter
040   * recognizes.
041   * 
042   * @return the picture type of this converter.
043   *
044   * @see com.avpkit.core.IPixelFormat.Type
045   */
046
047  public IPixelFormat.Type getPictureType();
048
049  /** Get the image type, as defined by {@link BufferedImage}, which
050   * this converter recognizes.
051   * 
052   * @return the image type of this converter.
053   *
054   * @see BufferedImage
055   */
056
057  public int getImageType();
058
059  /** Test if this converter is going to re-sample during conversion.
060   * For some conversions between {@link BufferedImage} and {@link
061   * IVideoPicture}, the IVideoPicture will need to be re-sampled into
062   * another pixel type, commonly between YUV and RGB types.  This
063   * re-sample is time consuming, and may not be available for
064   * all installations of AVPKit.
065   * 
066   * @return true if this converter will re-sample during conversion.
067   * 
068   * @see com.avpkit.core.IVideoResampler
069   * @see com.avpkit.core.IVideoResampler#isSupported(com.avpkit.core.IVideoResampler.Feature)
070   */
071
072  public boolean willResample();
073
074  /** Converts a {@link BufferedImage} to an {@link IVideoPicture}.
075   *
076   * @param image the source buffered image.
077   * @param timestamp the time stamp which should be attached to the the
078   *        video picture (in microseconds).
079   *
080   * @throws IllegalArgumentException if the passed {@link
081   *         BufferedImage} is NULL;
082   * @throws IllegalArgumentException if the passed {@link
083   *         BufferedImage} is not the correct type. See {@link
084   *         #getImageType}.
085   * @throws IllegalArgumentException if the underlying data buffer of
086   *         the {@link BufferedImage} is composed elements other bytes
087   *         or integers.
088   */
089
090  public IVideoPicture toPicture(BufferedImage image, long timestamp);
091
092  /** Converts an {@link IVideoPicture} to a {@link BufferedImage}.
093   *
094   * @param picture the source video picture.
095   *
096   * @throws IllegalArgumentException if the passed {@link
097   *         IVideoPicture} is NULL;
098   * @throws IllegalArgumentException if the passed {@link
099   *         IVideoPicture} is not the correct type. See {@link
100   *         #getPictureType}.
101   */
102
103  public BufferedImage toImage(IVideoPicture picture);
104
105  /** Return a written description of the converter. 
106   *
107   * @return a detailed description of what this converter does.
108   */
109
110  public String getDescription();
111  
112  /**
113   * Release any resources used by this converter.  Calls to
114   * the converter after this call are illegal and may fail
115   * in unspecified ways.  
116   */
117  public void delete();
118}