/tomo/pyhst

/*

 * The PyHST program is Copyright (C) 2002-2011 of the

 * European Synchrotron Radiation Facility (ESRF) and

 * Karlsruhe Institute of Technology (KIT).

 *

 * PyHST 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

 * (at your option) any later version.

 * 

 * hst 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 this program.  If not, see <http://www.gnu.org/licenses/>.

 */

#ifndef _PYHST_RECONSTRUCTOR_H

#define _PYHST_RECONSTRUCTOR_H

#include "hst_setup.h"

#include "hw_thread.h"

typedef struct HSTReconstructorT *HSTReconstructorPtr;

typedef struct HSTReconstructorContextT *HSTReconstructorContextPtr;

typedef const struct HSTReconstructorContextT *HSTReconstructorConstContextPtr;

/* Set of functions provided by reconstruction modules */

typedef const char *HSTConstString;

typedef HSTReconstructorContextPtr (*HSTCreateFunction)(HSTReconstructorPtr prototype, HSTSetup *setup, int id);

typedef int (*HSTInitFunction)(HSTReconstructorContextPtr ctx, HWThread thr);

typedef void (*HSTFreeFunction)(HSTReconstructorContextPtr ctx);

typedef void (*HSTDestroyFunction)(HSTReconstructorContextPtr ctx);

typedef int (*HSTConfigureFunction)(HSTReconstructorContextPtr ctx, HSTChanged what_changed);

typedef int (*HSTPreprocessFunction)(HSTReconstructorContextPtr ctx, float *result_slice, const float *sinograms);

typedef int (*HSTReconstructFunction)(HSTReconstructorContextPtr ctx, float *result_slice, const float *sinograms);

typedef int (*HSTPostprocessFunction)(HSTReconstructorContextPtr ctx, float *result_slice, const float *sinograms);

typedef int (*HSTSendFunction)(HSTReconstructorContextPtr ctx, const float *sinograms);

typedef int (*HSTWaitFunction)(HSTReconstructorContextPtr ctx);

typedef HSTConstString (*HSTGetReconstructorTitle)(HSTReconstructorConstContextPtr ctx);

typedef HSTConstString *(*HSTGetTimersFunction)(HSTReconstructorConstContextPtr ctx, double *timers);

enum HSTReconstructorFlagsT {

    HST_RECONSTRUCTOR_USE_CPU = 1,

    HST_RECONSTRUCTOR_USE_GPU = 2

};

typedef enum HSTReconstructorFlagsT HSTReconstructorFlags;

/**

 * Reconstructor module prototype describing the module capabilities and 

 * providing table of virtual functions

 */

struct HSTReconstructorT {

    int devices;				//!< Number of computational devices (CPU cores, standalone GPU units, ...)

    HSTGetReconstructorTitle get_title;    	//!< Function (mandatory)

    HSTCreateFunction create_context;		//!< Allocates memory for context (mandatory)

    HSTInitFunction init_context;		//!< Initializes context (mandatory)

    HSTFreeFunction free_context;		//!< Releases allocated resources (mandatory)

    HSTDestroyFunction destroy_context;		//!< Destroys context (mandatory)

    HSTConfigureFunction configure;		//!< Called then some of parameters are changed (optional)

    HSTSendFunction send;        

    HSTReconstructFunction preprocess;		//!< Preprocessor/Filtering step (optional)

    HSTReconstructFunction reconstruct;		//!< Backprojection step (mandatory)

    HSTReconstructFunction postprocess;		//!< Postprocessing step (optional)

    HSTWaitFunction wait;                       //!< Only after this function the results are guaranteed to be in the specified buffer

    HSTGetTimersFunction get_timers;		//!< Returns timing information (optional)

};

typedef struct HSTReconstructorT HSTReconstructor;

/**

 * The global properties of reconstructor context. The implementations (cpu/cuda/...) are extending 

 * this context with additional properties.

 */

struct HSTReconstructorContextT {

    HSTReconstructor recon;			//!< Copy of HSTReconstructor prototype

    HSTSetup *setup;				//!< Pointer on current HST setup

    float *saved_slice;                         //!< The sinograms for this slice were send to device during the last iteration

    const float *saved_sino;

    int processed_slices;			//!< Number of slices processed by the module

};

typedef struct HSTReconstructorContextT HSTReconstructorContext;

# ifdef __cplusplus

extern "C" {

# endif

/**

 * Initializes global portion of reconstructor context. This function should

 * be called from reconstructor initialization code (init_context function)

 *

 * before any other action

 * @param ctx is uninitialized HSTReconstructor context

 * @param recon is a pointer on reconstruction module prototype

 * @param setup is a pointer on structure holding HST parameters

 * @result non-zero error code in the case of error

 */

int hst_reconstructor_init_context(HSTReconstructorContext *ctx, HSTReconstructor *recon, HSTSetup *setup);

/**

 * Cleans up the global portion of reconstructor context. This function

 * should be called from reconstructor cleanup code (free_context function)

 * just before it returns control to the caller.

 *

 * @param ctx is cleaned reconstructor context

 */

void hst_reconstructor_free_context(HSTReconstructorContext *ctx);

/**

  * Default postprocessing routine

  * @param ctx is initialized HST context

  * @param slice is reconstructed slice

  * @param sinograms is containing all sinograms for that slice

  * @result non-zero error code in the case of error

  */

int hst_reconstructor_postprocess_slice(HSTReconstructorContext *ctx, float *slice, const float *sinograms);

# ifdef __cplusplus

}

# endif

#define HST_RECONSTRUCTOR(ctx) ((HSTReconstructor*)ctx)

#define hst_reconstructor_create(prototype, setup, id) prototype->create_context(prototype, setup, id)

#define hst_reconstructor_init(ctx, thr) HST_RECONSTRUCTOR(ctx)->init_context(ctx, thr)

#define hst_reconstructor_free(ctx) HST_RECONSTRUCTOR(ctx)->free_context(ctx)

#define hst_reconstructor_destroy(ctx) HST_RECONSTRUCTOR(ctx)->destroy_context(ctx)

#define hst_reconstructor_get_title(ctx) HST_RECONSTRUCTOR(ctx)->get_title(ctx)

#define hst_reconstructor_get_timers(ctx, timers) (HST_RECONSTRUCTOR(ctx)->get_timers?HST_RECONSTRUCTOR(ctx)->get_timers(ctx, timers):NULL)

#endif /* _PYHST_RECONSTRUCTOR_H */