rpnifs/rpn_if.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__h__
#define __rpn_if__h__

#include "config.h"

#include <assert.h>

#include "rpn_jit.h"

/**@file rpn_if.h
 * @ingroup ifs_if
 * @brief Iterated functions headers
 *
 * Iterated functions structure + API definition
 */

/**@defgroup ifs_if Iterated function
 * @ingroup ifs
 * @brief Iterated RPN expression
 *
 * @note For more details about Iterated function see dedicated
 * section : @ref doc_ifs_if
 *
 * Iterated function are function that can be iterated on successive position
 * in a memory map. The function takes its arguments from a position in the
 * memory map and output its results at a resulting position in the memory map.
 *
 * The iterated function can be seen as a function taking a position as argument
 * and outputing another position with borders effects from data stored at given
 * positions.
 *
 * The implementation try to be as generic as possible, allowing to implement
 * the transformation using a @ref rpn_expr_t system. The iterated function
 * has 2 functions as parameters :
 * - The first one @ref rpn_if_param_s.getarg_f transform a position
 *   to argument(s) and fetch the other arguments from the memory map
 * - The second @ref rpn_if_param_s.setres_f takes the results from the
 *   @ref rpn_expr_t system, transform it in position and results and set
 *   the memory map at resulting position with results.
 *
 * Based on this generic implementation @ref ifs_if_default are implemented for
 * various common cases : mutli-dimentionnal positions and constants, boolean,
 * colors as results.
 */

/**@brief Shortcut for struct @ref rpn_if_s */
typedef struct rpn_if_s rpn_if_t;
/**@brief Shortcut for struct @ref rpn_if_param_s */
typedef struct rpn_if_param_s rpn_if_param_t;

/**@brief Stores IF parameters and transformations function pointers */
struct rpn_if_param_s
{
	/**@brief Memory map size in items */
	size_t mem_sz;
	/**@brief Size of a memory item in bytes (should be a multiple of
	   sizeof(rpn_value_t))*/
	size_t value_sz;
	/**@brief RPN expression count */
	size_t rpn_sz;
	/**@brief Number of arguments expected by RPN expressions */
	size_t rpn_argc;

	/**@brief Sizeof RPN expression stacks */
	unsigned char rpn_stack_sz;

	/**@brief Set RPN arguments given a position
	 * @note transform position to arguments and fetch other arguments
	 * from memory map*/
	int (*getarg_f)(rpn_if_t *rif, size_t pos);
	/**@brief RPN results to data and position transformation
	 * @note set memory maps with converted data */
	int (*setres_f)(rpn_if_t *rif, size_t *pos);

	/**@brief Arbitrary data, if set must be freed in one free() call */
	void *data;
};

/**@brief Generic Iterated function implementation */
struct rpn_if_s
{
	/**@brief IF parameters */
	const rpn_if_param_t *params;
	/**@brief RPN expression(s) pointer(s) */
	rpn_expr_t *rpn;
	/**@brief RPN expression(s) result(s) buffer */
	rpn_value_t *rpn_res;
	/**@brief Arguments given to RPN expression(s) buffer */
	rpn_value_t *rpn_args;
	/**@brief Memory map in wich data are fetch & stored */
	rpn_value_t *mem;
	/**@brief If 1 the mmap is called at initialization time, munmap
	 * should be called by @ref rpn_if_free */
	short self_mem;
};

/**@brief Macro fetching a memory pointer given a position
 * @return rpn_value_t* values
 */
#define rpn_if_getitem(rif, pos) (rpn_value_t*)(((unsigned char*)rif->mem + ((rif->params->value_sz) * pos)))

/**@brief Alloc a new @ref rpn_if_s using given parameters
 * @param params IF parameters
 * @param memmap A suitable memory map. If NULL given, a new mmap is used
 * @param init_exprs If no NULL uses this expression (steal refs), else uses
 * 	new empty expressions
 * @return A pointer on an allocated @ref rpn_if_s
 */
rpn_if_t* rpn_if_new(const rpn_if_param_t *params, rpn_value_t *memmap,
		rpn_expr_t *init_exprs);

/**@brief Deallocate an @ref rpn_if_s and its ressources and close associated 
 * @ref rpn_expr_s
 * @param rif The IF to deallocate
 */
void rpn_if_free(rpn_if_t *rif);

/**@brief Run an IF
 * @param rif Pointer on IF
 * @param pos Input position
 * @return new position
 */
size_t rpn_if_step(rpn_if_t *rif, size_t pos);


/**@brief Returns the list of RPN expression : allowing to recompile them
 * @param rif Pointer on IF
 * @return A list of RPN expressions
 * @note The memory area returned must not be freed !
 */
rpn_expr_t **rpn_if_rpn_get(rpn_if_t *rif);


/**@brief New @ref rpn_if_s and partial initialisation
 * @param mem_sz memory size in bytes
 * @param rpn_argc number of arguments taken by @ref rpn_expr_s
 * @param rpn_count number of @ref rpn_expr_s
 * @param value_sz the count of rpn_value_t in one memory map value
 * @return a pointer on the initialized rif
 */
rpn_if_t* _rpn_if_new(size_t mem_sz, size_t rpn_argc, size_t rpn_count,
	size_t value_sz);

/**@page doc_ifs Iterated function system
 * @brief Iterated function system using RPN
 *
 * Iterated functions system are a composed of Iterated function choosed
 * randomly.
 *
 * @section doc_ifs_if Iterated function general considerations
 *
 * Iterated functions can be seen as transformations in a given space.
 * Functions takes items as argument and set an item as a result.
 *
 * For the moment, the main goal is to interact with a 2 dimension world with
 * 1 to 3 values per items (an image in grayscale or in RGB).
 *
 * A simple approach can be to use a single expression working with a single
 * number later decomposed in multiple composant using bitmasks (basically
 * for storage address and stored value).
 *
 * This can later be decomposed by assigning one (or multiple) expression
 * to each composant (one expression for storage address, another one for
 * the storage value).
 *
 * The same consideration can be done on argument number/composition taken
 * by the expression.
 *
 * @subsection doc_ifs_if_io Iterated function generalisation
 *
 * A generic implementation can be IF as :
 * - A generic input transformation system : X arguments transformed in Y
 * RPNExpression arguments
 * - A generic output system : N results (from N RPNExpr) transformed in X
 * results
 * - A generic transformation system : N expressions, taking Y arguments
 *
 * @section doc_ifs_if_api Iterated Function API
 *
 * Multiple steps are expected in API development :
 * - A simple generic API will be defined (something like expecting a
 * void* fun(void*) transforming X data in Y result using a blackbox optimized
 * behavior associated with a memory map
 * - Helper function will be written allowing C and/or Python extensions
 */

#endif