201 lines
6.9 KiB
C
201 lines
6.9 KiB
C
/*
|
|
* 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 "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
|
|
* @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);
|
|
|
|
/**@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
|
|
|