/******************************************************************************\
|*                                                                            *|
|*                           FingerCell Matcher 2.1                           *|
|*                                                                            *|
|* FncmMatchDetails.h                                                         *|
|* Header file for FncmMatchDetails module                                    *|
|*                                                                            *|
|* Copyright (C) 2006-2008 Neurotechnology                                    *|
|*                                                                            *|
\******************************************************************************/

#ifndef FNCM_MATCH_DETAILS_H_INCLUDED
#define FNCM_MATCH_DETAILS_H_INCLUDED

#include <NCore.h>

#ifdef N_CPP
extern "C"
{
#endif

/**
 * \brief Represents details of matching performed with FncMatcher.
 * 
 * FncmMatchDetails::CenterX X rotation point coordinate of the second (#FncmVerify or #FncmIdentifyNext) matched template. <br>
 * FncmMatchDetails::CenterY Y rotation point coordinate of the second (#FncmVerify or #FncmIdentifyNext) matched template. <br>
 * FncmMatchDetails::MatedMinutiaCount Number of mated minutiae in first and second matched NFRecords. <br>
 * FncmMatchDetails::MatedMinutiae Pointer to array of #NIndexPair containing pairs of indexes of mated minutiae in first and second matched NFRecords. <br>
 * FncmMatchDetails::Rotation 	 * The rotation is specified in 180/128 degrees units in counterclockwise order.
 *       To eliminate rotation, the second #NFRecord minutiae and singular points have to be rotated by the value around center of its minutiae bounding box. <br>
 * FncmMatchDetails::Score Similarity score of two matched #NFRecord. <br>
 * FncmMatchDetails::TranslationX Horizontal translation of second matched #NFRecord against the first one. <br>
 * FncmMatchDetails::TranslationY Vertical translation of second matched #NFRecord against the first one. <br>
 * 
 * \sa FncMatcher Module 
 */

typedef struct FncmMatchDetails_
{
	NInt Score; ///<Similarity score of two matched #NFRecord. 
	NInt Reserved;
	NInt CenterX; ///<X rotation point coordinate of the second (#FncmVerify or #FncmIdentifyNext) matched template. 
	NInt CenterY; ///<Y rotation point coordinate of the second (#FncmVerify or #FncmIdentifyNext) matched template. 
	NByte Rotation; ///<Rotation of second matched #NFRecord against the first one. 
	NInt TranslationX; ///<Horizontal translation of second matched #NFRecord against the first one. 
	NInt TranslationY; ///<Vertical translation of second matched #NFRecord against the first one. 
	NInt MatedMinutiaCount; ///<Number of mated minutiae in first and second matched NFRecords. 
	NIndexPair * MatedMinutiae; ///<Pointer to array of #NIndexPair containing pairs of indexes of mated minutiae in first and second matched NFRecords. 
} FncmMatchDetails;

/**
 * \brief Deserializes data from buffer into FncmMatchDetails structure.
 * 
 * \param[in] buffer Pointer to buffer containint serialized matching details 
 * \param[in] bufferLength length of the buffer containing the serialized matching details. 
 * \param[out] ppMatchDetails Pointer to FncmMatchDetails structure where the deserialized match details are put. 
 * 
 * \return  If the function succeeds the return value is #N_OK. 
 * \return  If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p pMatchDetails or \p pBuffer is NULL.  </td></tr>
 *            <tr><td>#N_E_FORMAT</td>
 *                <td>Data in buffer is inconsistent with #FncmMatchDetails structure format. </td></tr>
 *          </table>
 * \remark Memory for ppMatchDetails is allocated automatically so when this structure is not needed, it must be freed using #FncmMatchDetailsFree function. 
 * 
 * \ sa FncMatcher Module | HFncMatcher | FncmMatchDetails | FncmMatchDetailsFree 
 */
NResult N_API FncmMatchDetailsDeserialize(const void * buffer, NSizeType bufferLength, FncmMatchDetails * * ppMatchDetails);

/**
 * \brief Deletes #FncmMatchDetails.
 * 
 * \param[in] pMatchDetails Pointer to #FncmMatchDetails to delete. 
 * 
 * \remark If pMatchDetails is #NULL, does nothing.
 * 
 * \sa FncMatcher Module | FncmMatchDetails 
 */
void N_API FncmMatchDetailsFree(FncmMatchDetails * pMatchDetails);

/**
 * \brief Serializes #FncmMatchDetails structure into buffer.
 * 
 * \param[in] pMatchDetails Pointer to #FncmMatchDetails structure to be serialized. 
 * \param[out] pBuffer Pointer to buffer where serialized matching details structre is put. 
 * \param[out] pBufferLength Returns the size of the buffer allocated for the serialized matching details.  
 * 
 * \return  If the function succeeds the return value is #N_OK. 
 * \return  If the function fails, the return value is one of the following 
 *          error codes:
 *          <table>
 *            <tr><th>Error Code</th><th>Condition</th></tr>
 *            <tr><td>#N_E_ARGUMENT_NULL</td>
 *                <td>\p pMatchDetails or \p pBuffer is NULL.  </td></tr>
 *            <tr><td>#N_E_ARGUMENT</td>
 *                <td>Data in pMatchDetails is inconsistent with #FncmMatchDetails structure format. </td></tr>
 *          </table>
 * 
 * \remark After the data in pBuffer is not needed anymore, this buffer must be freed using #NFree function. 
 * 
 * \sa FncMatcher Module | HFncMatcher | FncmMatchDetails 
 */
NResult N_API FncmMatchDetailsSerialize(FncmMatchDetails * pMatchDetails, void * * pBuffer, NSizeType * pBufferLength);

#ifdef N_CPP
}
#endif

#endif // !FNCM_MATCH_DETAILS_H_INCLUDED
