rpnifs/rpn_if_default.h

/*
 * Copyright (C) 2020 Weber Yann
 * 
 * This file is part of pyrpn.
 * 
 * pyrpn is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * any later version.
 * 
 * pyrpn 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.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with pyrpn.  If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef __rpn_if_default__h__
#define __rpn_if_default__h__
#include "config.h"
#include "rpn_if.h"

/**@file rpn_if_default.h Defines default IF
 * @ingroup ifs_if_default
 * @ingroup ifs_if
 * @brief Default IF definitions
 */

/**@defgroup ifs_if_default Default iterated functions
 * @ingroup ifs_if
 * @brief Iterated function default implementation
 *
 * Defines default @ref rpn_if_param_s.setres_f and @ref rpn_if_param_s.getarg_f
 * functions and flags to select them (see @ref ifs_if_default_posflag and 
 * @ref ifs_if_default_resflag ).
 *
 * The @ref rpn_if_default_params function constructs suitable
 * @ref rpn_if_param_t to instanciate an @ref rpn_if_t with
 * @ref rpn_if_new function.
 */

/**@weakgroup ifs_if_default_posflag Default IF position flags
 * @ingroup ifs_if_default
 * @{ */
#define RPN_IF_POSITION_LINEAR 0 ///< One expr for position
#define RPN_IF_POSITION_XY 1 ///< two expr for position
#define RPN_IF_POSITION_XDIM 2 ///< X expr for position

#define RPN_IF_POSITION_OF_LOOP 0 ///< Loop on position overflow
#define RPN_IF_POSITION_OF_ERR 16 ///< Trigger error on position overflow
/**@}*/

/**@weakgroup ifs_if_default_resflag Default IF position flags
 * @ingroup ifs_if_default
 * @{ */
#define RPN_IF_RES_BOOL 0 ///< Set to one when position occurs
#define RPN_IF_RES_CONST 1 ///< Set to a constant value
#define RPN_IF_RES_CONST_RGBA 2 ///< Set to a constant RGB using alpha channel
#define RPN_IF_RES_COUNT 3 ///< Count number of time position occurs
#define RPN_IF_RES_XFUN 4 ///< Set to result of rpn_expr
#define RPN_IF_RES_RGB 5 ///< Set result to RGB color from rpn_expr
#define RPN_IF_RES_RGBA 6 ///< Set result to RGB using alpha channel from rpn_expr
/**@}*/

/**@brief Alias for struct @ref rpn_if_default_data_s */
typedef struct rpn_if_default_data_s rpn_if_default_data_t;

/**@brief Stores default IF data
 *
 * Stores flags and size limit
 * @ingroup ifs_if_default
 */
struct rpn_if_default_data_s
{
	/**@brief Flag defining position coordinate handling */
	short pos_flag;
	/**@brief Flag defining result handling */
	short res_flag;
	/**@brief Stores size limits given pos_flag
	 *
	 * @note If NULL no limit
	 * - For @ref RPN_IF_POSITION_LINEAR size_lim is a single size_t
	 * - For @ref RPN_IF_POSITION_XY size_lim is two size_t (height and width)
	 * - For @ref RPN_IF_POSITION_XDIM the first element (*size_lim) is the
	 *   size of the size_lim array
	 */
	size_t *size_lim;

	/** Number of dimensions (if XDIM ndim = len(size_lim)-1) */
	size_t ndim;

	/**@brief Store constant values to set mem given res_flag
	 * - For @ref RPN_IF_RES_CONST const_val points on a single value
	 * - For @ref RPN_IF_RES_CONST_RGBA const_val points on 4 values
	 * - Else const_val is set to NULL
	 */
	rpn_value_t *const_val;
};

/**@brief Create a new @ref rpn_if_param_s corresponding to given flags
 * @ingroup ifs_if_default
 *
 * @param pos_flag Binary OR combination of RPN_IF_POSITION_*
 *     (@ref ifs_if_default_posflag )
 * @param res_flag Binary OR combination of RPN_IF_RES_*
 *     (@ref ifs_if_default_resflag )
 * @param lim Depends on pos_flag parameter (
 *	see @ref rpn_if_default_data_s::size_lim )
 * @param res_const Depends on res_flag parameter (
 *	see @ref rpn_if_default_data_s::const_val )
 * @param rpn_stack_sz The size of the stack for expressions
 * @returns A new @ref rpn_if_param_t or NULL on error
 * @ingroup ifs_if_default
 */
rpn_if_param_t* rpn_if_default_params(short pos_flag, short res_flag,
	const size_t *lim, const rpn_value_t *res_const,
	unsigned char rpn_stack_sz);

/** Fetch size limit and const values array sizes given flag values
 *  @param pos_flag (@ref ifs_if_default_posflag)
 *  @param res_flag (@ref ifs_if_default_resflag)
 *  @param sizes size limit array size and constant values array size
 *  @return 0 or -1 if a flag is not valid
 *  @warning returns 1 for size limit when XDIM position, but actually the
 *  limit is given by the 1st number in the limit (example : [2,640,480],
 *  [3,16,640,480], ...)
 *  @todo replace short by int for sizes
 */
int rpn_if_sizes_from_flag(short pos_flag, short res_flag, short sizes[2]);

/**@brief Default argf function ( see @ref rpn_if_param_s.getarg_f )
 *
 * This function handle internal rif modification to set next arguments.
 * It will call specialized function depending on
 * @ref rpn_if_default_data_s.pos_flag and @ref rpn_if_default_data_s.res_flag
 * @note The position is the first set of arguments and can be use to
 * look for the other one
 *
 * @param rif Pointer on expressions
 * @param pos The position
 * @return 0 or -1 on error
 */
int rpn_if_getarg_default(rpn_if_t *rif, size_t pos);

/**@brief Default result function ( see @ref rpn_if_param_s.setres_f )
 *
 * This function will store the result at given position and 
 * It will call specialized function depending on
 * @ref rpn_if_default_data_s.pos_flag and @ref rpn_if_default_data_s.res_flag
 * @param rif Pointer on expressions
 * @param pos Will be set to the resulting position
 * @return 0 or -1 on error
 */
int rpn_if_setres_default(rpn_if_t *rif, size_t *pos);

/**@brief Set the first expression argument from linear position
 * @param rif Expressions
 * @param pos Memory map offset
 * @param args pointer on expressions arguments
 * @return 0 or -1 on error
 * @note Other arguments are set using the generic @ref rpn_if_getarg_default
 * function
 */
int rpn_if_argf_linear(rpn_if_t *rif, size_t pos, rpn_value_t *args);
/**@brief Transform 1st expression result to position 
 * @param rif Expressions
 * @param pos Pointer on resulting position in memory map
 * @return 0 or -1 on error
 * @note Data from position fecth is done by generic @ref rpn_if_setres_default
 * function
 */
int rpn_if_resf_linear(rpn_if_t *rif, size_t *pos);

/**@brief Set the 1st & 2nd argument from position
 * @param rif Expressions
 * @param pos Memory map offset
 * @param args pointer on expression arguments
 * @return 0 or -1 on error
 * @note Other arguments are set using the generic @ref rpn_if_getarg_default
 * function
 */
int rpn_if_argf_xy(rpn_if_t *rif, size_t pos, rpn_value_t *args);
/**@brief Transform 1st and 2nd result into a memory map's offset
 * @param rif Expressions
 * @param pos Memory map offset pointer
 * @return 0 or -1 on error
 * @note Data from position fetch is done by generic @ref rpn_if_setres_default
 * function
 */
int rpn_if_resf_xy(rpn_if_t *rif, size_t *pos);

/**@brief Set X first arguments from position
 * @param rif Expressions
 * @param pos Memory map offset
 * @param args Pointer on expression arguments
 * @return 0 or -1 on error
 * @note Other arguments are set using the generic @ref rpn_if_getarg_default
 * function
 */
int rpn_if_argf_xdim(rpn_if_t *rif, size_t pos, rpn_value_t *args);
/**@brief Transform X arguments into a memory map's offset
 * @param rif Expressions
 * @param pos Memory map offset pointer
 * @return 0 or -1 on error
 * @note Data from position fetch is done by generic @ref rpn_if_setres_default
 * function
 */
int rpn_if_resf_xdim(rpn_if_t *rif, size_t *pos);

#endif