/*
 * ikaleid0sc0pe.h
 * Copyright (C) 2020-2023 Brendan Hack (github@bendys.com)
 * This file is part of a Frei0r plugin that applies a kaleidoscope
 * effect.
 * Version 1.1	july 2023
 *
 * Interface and factory function to the kaleidoscope library
 *
 * This source code is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * This source code is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. Please refer
 * to the GNU Public License for more details.
 *
 * You should have received a copy of the GNU Public License along
 * with this source code; if not, write to: Free Software Foundation,
 * Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 *
 */
#ifndef SRC_FILTER_KALEID0SC0PE_IKALEID0SC0PE_H_
#define SRC_FILTER_KALEID0SC0PE_IKALEID0SC0PE_H_ 1

#include <cstdint>
#include <memory>

namespace libkaleid0sc0pe {
class IKaleid0sc0pe;
}

namespace std
{

// default delete for IKaleid0sc0pe
// this isn't going to work across an actual shared object boundary but
// not particular worried about that at the moment
template<>
class default_delete<libkaleid0sc0pe::IKaleid0sc0pe>
{
public:
    void operator()(libkaleid0sc0pe::IKaleid0sc0pe* p);
};

} // namespace std

namespace libkaleid0sc0pe {

/**
 * Class which implements the kaleid0sc0pe effect
 */
class IKaleid0sc0pe {
public:
    /**
     * Sets the origin of the kaleid0sc0pe effect. These are given in the range 0 -> 1.
     * Values other than 0.5,0.5 may end up reflecting outside the source image.
     * These areas will be filled depending on the settings in #set_reflect_edges and
     * #set_background_colour.
     * Defaults to 0.5, 0.5.
     * @param x x coordinate of the origin
     * @param y y coordinate of the origin
     * @return
     *          -  0: Success
     *          - -1: Error
     *          - -2: Parameter out of range
     */
    virtual std::int32_t set_origin(float x, float y) = 0;

    /**
     * Returns the origin x coordinate.
     */
    virtual float get_origin_x() const = 0;

    /**
     * Returns the origin y coordinate.
     */
    virtual float get_origin_y() const = 0;

    /**
     * Sets the segmentation resulting in \p segmentation * 2 segments in the output frame.
     * Segmentation values that are 1, 2 or a multiple of 4, are oriented to an image corner
     * and centred will always reflect back to the source segment.
     * Other settings may end up reflecting outside the source image. These areas will be filled
     * depending on the settings in #set_reflect_edges and #set_background_colour.
     * Defaults to 16.
     * @param segmentation the segmentation value
     * @return
     *          -  0: Success
     *          - -1: Error
     *          - -2: Parameter out of range
     */
    virtual std::int32_t set_segmentation(std::uint32_t segmentation) = 0;

    /**
     * Returns the segmentation value
     */
    virtual std::uint32_t get_segmentation() const = 0;

    /**
     * When #set_reflect_edges is not true and a reflected pixel ends up outside the image
     * we can clamp the pixels that fall outside the image but within \p threshold pixels
     * of the edge to the edge.
     * Defaults to 0
     * @param threshold the threshold in pixels.
     * @return
     *          -  0: Success
     *          - -1: Error
     */
    virtual std::int32_t set_edge_threshold(std::uint32_t threshold) = 0;

    /**
     * Returns the edge threshold
     */
    virtual std::uint32_t get_edge_threshold() const = 0;

    ///  Defines a corner
    enum class Corner {
        TL = 0,     //< Top Left
        TR,         //< Top Right
        BR,         //< Bottom Right
        BL          //< Bottom Left
    };

    ///  Defines an angular direction
    enum class Direction {
        CLOCKWISE = 0,  //< Clockwise
        ANTICLOCKWISE,  //< Anti Clockwise
        NONE            //< No direction
    };

    /**
     * Sets the direction that the source segment rotates in. If
     * Direction::NONE then the source segment is centred on the corner.
     * Otherwise it extends in the given direction.
     * Defaults to Direction::NONE
     * @param direction the direction
     * @return
     *          -  0: Success
     *          - -1: Error
     */
    virtual std::int32_t set_segment_direction(Direction direction) = 0;

    /**
     * Returns the segment direction
    */
    virtual Direction get_segment_direction() const = 0;

    /**
     * Unless directly specified with #set_source_segment the source segment is always aligned to
     * the furthest corner of the image from the origin.
     * The source segment has it's edge (or centre) on a line from the origin to the furthest corner,
     * and extends in the direction given by #set_segment_direction.
     * If multiple corners are equidistant from the origin then this indicates which
     * corner is preferred. The algorithm searches from this corner, in the direction
     * specified in #set_preferred_corner_search_direction to find the furthest corner.
     * Defaults to Corner::BR
     * @param corner the preferred corner
     * @return
     *          -  0: Success
     *          - -1: Error
     */
    virtual std::int32_t set_preferred_corner(Corner corner) = 0;

    /**
     * Returns the preferred corner
     */
    virtual Corner get_preferred_corner() const = 0;

    /**
     * The direction to search for the furthest corner in.
     * Defaults to Direction::CLOCKWISE
     * @param direction the search direction
     * @return
     *          -  0: Success
     *          - -1: Error
     *          - -2: Invalid parameter (\p direction cannot by Direction::NONE)
     */
    virtual std::int32_t set_preferred_corner_search_direction(Direction direction) = 0;

    /**
     * Returns the corner search direction
     */
    virtual Direction get_preferred_corner_search_direction() const = 0;

    /**
     * Reflected points can end up outside the source image depending on segmentation,
     * source segment and origin settings. When this occurs three options are provided,
     * lookup the pixel in a reflected tessellation of the original image, set the pixel
     * to the background colour provided in #set_background_colour or write nothing to the
     * output frame for that pixel.
     * Defaults to \c true which is to lookup in the reflected tessellation.
     * @param reflect if \c true then lookup in a reflection, if \c false use background color
     * or do nothing if no background color was set.
     * @return
     *          -  0: Success
     *          - -1: Error
     */
    virtual std::int32_t set_reflect_edges(bool reflect) = 0;

    /**
     * Returns the reflect edges setting
     */
    virtual bool get_reflect_edges() const = 0;

    /**
     * If not reflecting edges then this sets the colour to use when the kaleid0sc0pe effect
     * for a point ends up outside the source image. The data pointed to should be at least as
     * wide as a pixel and must be valid for  the lifetime of the class instance.
     * The caller retains ownership of the passed memory.
     * Defaults to \c nullptr
     * @param colour the background colour, if \c nullptr then the output buffer is not modified
     * if reflection does not land in the source segment.
     * @return
     *          -  0: Success
     *          - -1: Error
     */
    virtual std::int32_t set_background_colour(void* colour) = 0;

    /**
     * Returns the background colour
     */
    virtual void* get_background_colour() const = 0;

    /**
     * Allows to explicitly specify the location of the source segment. 0 radians is in the positive
     * horizontal direction and +ve rotates anti-clockwise.
     * @param angle If positive or 0 then the angle of the centre of the source segment in radians. If negative
     * (the default) then the source segment is auto calculated based on origin, preferred corner,
     * direction and corner search direction.
     * @return
     *          -  0: Success
     *          - -1: Error
     */
    virtual std::int32_t set_source_segment(float angle) = 0;

    /**
     * Returns the source segment
     */
    virtual float get_source_segment() const = 0;

    /**
     * Applies the kaleid0sc0pe effect to \p in_frame and returns it in \p out_frame.
     * Each parameter must point to enough memory to contain the image specified in the
     * constructor and must be aligned to an integer multiple of 16 bytes in memory.
     * @param in_frame the input frame to process
     * @param out_frame receives the output image
     * @return
     *          -  0: Success
     *          - -1: Error
     *          - -2: Invalid parameter (nullptr)
     */
    virtual std::int32_t process(const void* in_frame, void* out_frame) = 0;

    /**
     * Sets the number of threads to use when processing.
     * Default to 0.
     * @param threading the number of threads to use. \c 0, calculate automatically,
     * otherwise the explicit thread count.
     * @return
     *          -  0: Success
     *          - -1: Error
     */
    virtual std::int32_t set_threading(std::uint32_t threading) = 0;

    /**
     * Returns the number of threads to use.
     */
    virtual std::uint32_t get_threading() const = 0;

    /**
     * Visualises the currently configured segmentation. The pure green segment is the
     * source segment.
     * @param out_frame receives the output image
     * @return
     *          -  0: Success
     *          - -1: Error
     *          - -2: Invalid parameter (nullptr)
     */
    virtual std::int32_t visualise(void* out_frame) = 0;

    /**
     * Virtual destructor
     */
    virtual ~IKaleid0sc0pe() {};

    /**
     * Static factory function. Frame width and height must be a multiple of 4.
     * @param width the frame width
     * @param height the frame height
     * @param component_size the byte size of each frame pixel component
     * @param num_components the number of components per pixel
     * @param stride the image stride, if \c 0 then calculated as \p width * \p component_size * \p num_components
     */
    static std::unique_ptr<IKaleid0sc0pe> factory(std::uint32_t width, std::uint32_t height, std::uint32_t component_size, std::uint32_t num_components, std::uint32_t stride = 0) {
        return std::unique_ptr<IKaleid0sc0pe>(create(width, height, component_size, num_components, stride));
    }

private:
    static IKaleid0sc0pe* create(std::uint32_t width, std::uint32_t height, std::uint32_t component_size, std::uint32_t num_components, std::uint32_t stride = 0);

};

} // namespace libkaleid0sc0pe

#endif // SRC_FILTER_KALEID0SC0PE_IKALEID0SC0PE_H_