Top-level library interface


Data Structures

struct  gs_hdr_tag
struct  tc_hdr_tag
struct  eps_block_header_tag

Defines

#define EPS_MARKER   0x00
#define EPS_GRAYSCALE_BLOCK   1
#define EPS_TRUECOLOR_BLOCK   2
#define EPS_MAX_BLOCK_SIZE   1024
#define EPS_MIN_BLOCK_SIZE   32
#define EPS_MIN_GRAYSCALE_BUF   256
#define EPS_MAX_GRAYSCALE_BUF   2 * EPS_MAX_BLOCK_SIZE * EPS_MAX_BLOCK_SIZE
#define EPS_MIN_TRUECOLOR_BUF   256
#define EPS_MAX_TRUECOLOR_BUF   6 * EPS_MAX_BLOCK_SIZE * EPS_MAX_BLOCK_SIZE
#define EPS_MODE_NORMAL   0
#define EPS_MODE_OTLPF   1
#define EPS_GOOD_CRC   0
#define EPS_BAD_CRC   1
#define EPS_FB_ID   0
#define EPS_FB_NAME   1
#define EPS_FB_TYPE   2
#define EPS_Y_RT   90
#define EPS_Cb_RT   5
#define EPS_Cr_RT   5
#define EPS_MIN_RT   1
#define EPS_MAX_RT   98
#define EPS_RESAMPLE_444   0
#define EPS_RESAMPLE_420   1
#define EPS_OK   0
#define EPS_PARAM_ERROR   1
#define EPS_FORMAT_ERROR   2
#define EPS_UNSUPPORTED_FB   3

Typedefs

typedef uint32_t crc32_t
typedef struct gs_hdr_tag gs_hdr
typedef struct tc_hdr_tag tc_hdr
typedef struct eps_block_header_tag eps_block_header

Functions

char ** eps_get_fb_info (int type)
void eps_free_fb_info (char **info)
void ** eps_xmalloc (int size)
void ** eps_malloc_2D (int width, int height, int size)
void eps_free_2D (void **ptr, int width, int height)
int eps_read_block_header (unsigned char *buf, int buf_size, eps_block_header *hdr)
int eps_encode_grayscale_block (unsigned char **block, int W, int H, int w, int h, int x, int y, unsigned char *buf, int *buf_size, char *fb_id, int mode)
int eps_decode_grayscale_block (unsigned char **block, unsigned char *buf, eps_block_header *hdr)
int eps_encode_truecolor_block (unsigned char **block_R, unsigned char **block_G, unsigned char **block_B, int W, int H, int w, int h, int x, int y, int resample, unsigned char *buf, int *buf_size, int Y_rt, int Cb_rt, int Cr_rt, char *fb_id, int mode)
int eps_decode_truecolor_block (unsigned char **block_R, unsigned char **block_G, unsigned char **block_B, unsigned char *buf, eps_block_header *hdr)
int eps_truncate_block (unsigned char *buf_in, unsigned char *buf_out, eps_block_header *hdr, int *truncate_size)

Detailed Description


Define Documentation

#define EPS_MARKER   0x00

Block marker

Each block in the stream should be terminated with one or more EPS_MARKER values. This technique greatly improves overall system robustness and leads to quick stream resynchronization.

#define EPS_GRAYSCALE_BLOCK   1

GRAYSCALE block

This type of blocks is intended for storing grayscale image data.

Referenced by eps_read_block_header().

#define EPS_TRUECOLOR_BLOCK   2

TRUECOLOR block

This type of blocks is intended for storing truecolor image data.

Referenced by eps_read_block_header().

#define EPS_MAX_BLOCK_SIZE   1024

Maximal (recomended) block width and height

Referenced by eps_encode_grayscale_block(), eps_encode_truecolor_block(), read_gs_header(), and read_tc_header().

#define EPS_MIN_BLOCK_SIZE   32

Minimal (recomended) block width and height

#define EPS_MIN_GRAYSCALE_BUF   256

Minimal (mandatory) buffer size for GRAYSCALE block

Referenced by eps_encode_grayscale_block(), and eps_truncate_block().

#define EPS_MAX_GRAYSCALE_BUF   2 * EPS_MAX_BLOCK_SIZE * EPS_MAX_BLOCK_SIZE

Maximal (recomended) buffer size for GRAYSCALE block

#define EPS_MIN_TRUECOLOR_BUF   256

Minimal (mandatory) buffer size for TRUECOLOR block

Referenced by eps_encode_truecolor_block(), and eps_truncate_block().

#define EPS_MAX_TRUECOLOR_BUF   6 * EPS_MAX_BLOCK_SIZE * EPS_MAX_BLOCK_SIZE

Maximal (recomended) buffer size for TRUECOLOR block

#define EPS_MODE_NORMAL   0

Normal mode

This mode assumes that image is square and height = width = 2 ^ N.

Referenced by eps_encode_grayscale_block(), eps_encode_truecolor_block(), get_block_size(), read_gs_header(), and read_tc_header().

#define EPS_MODE_OTLPF   1

OTLPF mode

This mode also assumes that image is square, but height = width = (2 ^ N) + 1. In a few words, OTLPF is some kind of hack to reduce boundary artefacts when image is broken into several tiles. Due to mathematical constrains this method can be applied to biorthogonal filters only.

Referenced by eps_decode_truecolor_block(), eps_encode_grayscale_block(), eps_encode_truecolor_block(), read_gs_header(), and read_tc_header().

#define EPS_GOOD_CRC   0

Data or header CRC is correct

Referenced by read_gs_header(), and read_tc_header().

#define EPS_BAD_CRC   1

Data or header CRC is incorrect

Referenced by read_gs_header(), and read_tc_header().

#define EPS_FB_ID   0

Extract all filterbank IDs

Referenced by eps_get_fb_info().

#define EPS_FB_NAME   1

Extract all filterbank names

Referenced by eps_get_fb_info().

#define EPS_FB_TYPE   2

Extract all filterbank orthogonality types

Referenced by eps_get_fb_info().

#define EPS_Y_RT   90

Default bit-budget percent for the Y channel

#define EPS_Cb_RT   5

Default bit-budget percent for the Cb channel

#define EPS_Cr_RT   5

Default bit-budget percent for the Cr channel

#define EPS_MIN_RT   1

Minimal value for bit-budget percent value

Referenced by eps_encode_truecolor_block().

#define EPS_MAX_RT   98

Maximal value for bit-budget percent value

#define EPS_RESAMPLE_444   0

Perform no image resampling

Referenced by eps_decode_truecolor_block(), eps_encode_truecolor_block(), and read_tc_header().

#define EPS_RESAMPLE_420   1

Resample image according to the 4:2:0 scheme

Referenced by eps_encode_truecolor_block(), and read_tc_header().

#define EPS_OK   0

#define EPS_PARAM_ERROR   1

#define EPS_FORMAT_ERROR   2

#define EPS_UNSUPPORTED_FB   3


Typedef Documentation

typedef uint32_t crc32_t

Type definition for CRC32 value

typedef struct gs_hdr_tag gs_hdr

GRAYSCALE block header

typedef struct tc_hdr_tag tc_hdr

TRUECOLOR block header

Generic block header


Function Documentation

char** eps_get_fb_info ( int  type  ) 

Query available filterbanks

Depending on the type parameter this function composes a NULL terminated list of all available filterbank IDs, names or orthogonality types.

Note:
The caller should subsequently release allocated list (using eps_free_fb_info function) when it is no longer required.

The caller should not modify allocated structure.

Parameters:
type Type of information: either EPS_FB_ID or EPS_FB_NAME or EPS_FB_TYPE
Returns:
List of strings

References BIORTHOGONAL, EPS_FB_ID, EPS_FB_NAME, EPS_FB_TYPE, filterbanks, filterbank_t_tag::id, filterbank_t_tag::name, and xmalloc().

void eps_free_fb_info ( char **  info  ) 

Release filterbank information

This function releases filterbank infomation, allocated by the eps_get_fb_info function.

Parameters:
info List of strings
Returns:
VOID

void** eps_xmalloc ( int  size  ) 

Memory allocation

This function allocates one-dimensional array of desired size.

Parameters:
size Size in bytes
Returns:
Array pointer
Warning:
This function halts the program if all virtual memory is exhausted.

References xmalloc().

void** eps_malloc_2D ( int  width,
int  height,
int  size 
)

2D-malloc

This function allocates two-dimensional array of desired size.

Parameters:
width Array width
height Array height
size Element size
Returns:
Array pointer
Warning:
This function halts the program if all virtual memory is exhausted.

References malloc_2D().

void eps_free_2D ( void **  ptr,
int  width,
int  height 
)

2D-free

This function releases two-dimensional array allocated by eps_malloc_2D.

Parameters:
ptr Array pointer
width Array width
height Array height
Returns:
VOID

References free_2D().

int eps_read_block_header ( unsigned char *  buf,
int  buf_size,
eps_block_header hdr 
)

Read block header

This function performes a broad range of tasks:

  • Read and parse block header
  • Check header consistency
  • Check header and data CRC
  • Fill special eps_block_header structure with gathered information (it is worthwhile to mention that all decoding functions in the library rely on this structure)

The eps_block_header structure consists of two parts: general part and special part. The first one holds information that is common for all block types. The second one holds information that is specific for a particular block type.

Note:
The data buffer buf should hold whole block without markers.
Parameters:
buf Data buffer
buf_size Buffer size
hdr Block header
Returns:
The function returns either EPS_OK (the header is well-formed, the hdr structure is filled appropriately) or EPS_PARAM_ERROR (your should not get this error unless you pass a NULL pointer, negative buffer size or something like that) or EPS_FORMAT_ERROR (the header is malformed, block should be ignored).

References eps_block_header_tag::block_type, EPS_FORMAT_ERROR, EPS_GRAYSCALE_BLOCK, EPS_OK, EPS_PARAM_ERROR, EPS_TRUECOLOR_BLOCK, read_gs_header(), read_tc_header(), terminate_header(), and unterminate_header().

int eps_encode_grayscale_block ( unsigned char **  block,
int  W,
int  H,
int  w,
int  h,
int  x,
int  y,
unsigned char *  buf,
int *  buf_size,
char *  fb_id,
int  mode 
)

Encode a GRAYSCALE block

This function encodes a signle grayscale image block of size w by h pixels as block of type EPS_GRAYSCALE_BLOCK. It is assumed that the block is taken from the image of size W by H pixels at position (x, y). All these parameters should be consistent. The encoded data is stored in the buf of size buf_size.

Note:
The most surprising thing here is that you can choose almost any (see note below) buf_size you wish! Thus you can precisely control encoding bit-rate. This technique is called embedded coding. In a few words, any encoded prefix can be used to decode a whole image. So, you can safely truncate stream at any point.

The caller should allocate at least EPS_MIN_GRAYSCALE_BUF bytes for the buf.

On successful return, the value pointed by the buf_size will be overwritten with a real amount of bytes used in the buf (it will be less then or equal to the original buf_size value).

Depending on the mode parameter maximal block width or height is either EPS_MAX_BLOCK_SIZE (if mode = EPS_MODE_NORMAL) or EPS_MAX_BLOCK_SIZE + 1 (if mode = EPS_MODE_OTLPF).

There is no restrictions on the image size itself.

The caller should select a value for the fb_id parameter from the list generated by the eps_get_fb_info function.

The caller should not use orthogonal filterbanks with mode = EPS_MODE_OTLPF. Orthogonality type can be queried with the eps_get_fb_info function.

Parameters:
block Image block
W Image width
H Image height
w Block width
h Block height
x Block X coordinate
y Block Y coordinate
buf Buffer
buf_size Buffer size
fb_id Filterbank ID
mode Either EPS_MODE_NORMAL or EPS_MODE_OTLPF
Returns:
The function returns either EPS_OK (the block is successfully encoded), or EPS_PARAM_ERROR (one or more parameters are incorrect) or EPS_UNSUPPORTED_FB (filterbank with specified fb_id not found).

References analysis_2D(), CLIP, dc_level_shift(), EPS_MAX_BLOCK_SIZE, EPS_MIN_GRAYSCALE_BUF, EPS_MODE_NORMAL, EPS_MODE_OTLPF, EPS_OK, EPS_PARAM_ERROR, EPS_UNSUPPORTED_FB, epsilon_crc32(), extend_channel(), free_2D(), get_block_size(), get_fb(), malloc_2D(), MIN, ORTHOGONAL, round_channel(), speck_encode(), stuff_data(), filterbank_t_tag::type, and xmalloc().

int eps_decode_grayscale_block ( unsigned char **  block,
unsigned char *  buf,
eps_block_header hdr 
)

Decode a GRAYSCALE block

This function decodes a GRAYSCALE image block from the buf. Block and image dimensions as well as other necessary information is taken from the hdr structure filled by the eps_read_block_header function beforehand.

Note:
The caller should not invoke this function if the buf contains no data, i.e. eps_block_header::data_size = 0.

The caller should allocate an image block beforehand. Block dimensions as well as other information is available in the hdr structure.

Parameters:
block Image block
buf Buffer
hdr Block header
Returns:
The function returns either EPS_OK (the block is successfully decoded), or EPS_PARAM_ERROR (one or more parameters are incorrect) or EPS_UNSUPPORTED_FB (filterbank used by encoder not found).

References copy_channel(), eps_block_header_tag::data_size, gs_hdr_tag::dc, dc_level_unshift(), EPS_OK, EPS_PARAM_ERROR, EPS_UNSUPPORTED_FB, extract_channel(), gs_hdr_tag::fb_id, free_2D(), get_block_size(), get_fb(), eps_block_header_tag::gs, gs_hdr_tag::h, eps_block_header_tag::hdr_data, eps_block_header_tag::hdr_size, malloc_2D(), gs_hdr_tag::mode, reset_Y(), speck_decode(), synthesis_2D(), unstuff_data(), gs_hdr_tag::w, and xmalloc().

int eps_encode_truecolor_block ( unsigned char **  block_R,
unsigned char **  block_G,
unsigned char **  block_B,
int  W,
int  H,
int  w,
int  h,
int  x,
int  y,
int  resample,
unsigned char *  buf,
int *  buf_size,
int  Y_rt,
int  Cb_rt,
int  Cr_rt,
char *  fb_id,
int  mode 
)

Encode a TRUECOLOR block

This function encodes a generic RGB truecolor image block. The original RGB data is arranged in three arrays: block_R, block_G and block_B respectively. All components should have equal dimensions: w by h pixels. It is assumed that the block is taken from the image of size W by H pixels at position (x, y). All these parameters should be consistent. The encoded data is stored in the buf of size buf_size.

Note:
The most surprising thing here is that you can choose almost any (see note below) buf_size you wish! Thus you can precisely control encoding bit-rate. This technique is called embedded coding. In a few words, any encoded prefix can be used to decode a whole image. So, you can safely truncate stream at any point.

The caller should allocate at least EPS_MIN_TRUECOLOR_BUF bytes for the buf.

The overall bit-budget available for the encoder is buf_size bytes. The caller should divide it between three channels (Y, Cb, Cr) using the following parameters: Y_rt, Cb_rt and Cr_rt. The function will report an error unless Y_rt + Cb_rt + Cr_rt equals to 100%. If no matter you can use default values: EPS_Y_RT, EPS_Cb_RT and EPS_Cr_RT.

On successful return, the value pointed by the buf_size will be overwritten with a real amount of bytes used in the buf (it will be less then or equal to the original buf_size value).

Depending on the mode parameter maximal block width or height is either EPS_MAX_BLOCK_SIZE (if mode = EPS_MODE_NORMAL) or EPS_MAX_BLOCK_SIZE + 1 (if mode = EPS_MODE_OTLPF).

There is no restrictions on the image size itself.

The caller should select a value for the fb_id parameter from the list generated by the eps_get_fb_info function.

The caller should not use orthogonal filterbanks with mode = EPS_MODE_OTLPF. Orthogonality type can be queried with the eps_get_fb_info function.

Parameters:
block_R Red component
block_G Green component
block_B Blue component
W Image width
H Image height
w Block width
h Block height
x Block X coordinate
y Block Y coordinate
resample Resampling scheme: either EPS_RESAMPLE_444 or EPS_RESAMPLE_420
buf Buffer
buf_size Buffer size
Y_rt Bit-budget percent for the Y channel
Cb_rt Bit-budget percent for the Cb channel
Cr_rt Bit-budget percent for the Cr channel
fb_id Filterbank ID
mode Either EPS_MODE_NORMAL or EPS_MODE_OTLPF
Returns:
The function returns either EPS_OK (the block is successfully encoded), or EPS_PARAM_ERROR (one or more parameters are incorrect) or EPS_UNSUPPORTED_FB (filterbank with specified fb_id not found).

References analysis_2D(), bilinear_resample_channel(), CLIP, convert_RGB_to_YCbCr(), dc_level_shift(), EPS_MAX_BLOCK_SIZE, EPS_MIN_RT, EPS_MIN_TRUECOLOR_BUF, EPS_MODE_NORMAL, EPS_MODE_OTLPF, EPS_OK, EPS_PARAM_ERROR, EPS_RESAMPLE_420, EPS_RESAMPLE_444, EPS_UNSUPPORTED_FB, epsilon_crc32(), extend_channel(), free_2D(), get_block_size(), get_fb(), malloc_2D(), MAX, merge_channels(), MIN, ORTHOGONAL, round_channel(), speck_encode(), stuff_data(), filterbank_t_tag::type, and xmalloc().

int eps_decode_truecolor_block ( unsigned char **  block_R,
unsigned char **  block_G,
unsigned char **  block_B,
unsigned char *  buf,
eps_block_header hdr 
)

Decode a TRUECOLOR block

This function decodes a TRUECOLOR image block from the buf. The resulted RGB data will be stored in the block_R, block_G, and block_B arrays respectively. Block and image dimensions as well as other necessary information is taken from the hdr structure filled by the eps_read_block_header function beforehand.

Note:
The caller should not invoke this function if the buf contains no data, i.e. eps_block_header::data_size = 0.

The caller should allocate block_R, block_G, and block_B arrays beforehand. Block dimensions as well as other information is available in the hdr structure.

Parameters:
block_R Red component
block_G Green component
block_B Blue component
buf Buffer
hdr Block header
Returns:
The function returns either EPS_OK (the block is successfully decoded), or EPS_PARAM_ERROR (one or more parameters are incorrect) or EPS_UNSUPPORTED_FB (filterbank used by encoder not found) or EPS_FORMAT_ERROR (unsupported data format).

References bilinear_resample_channel(), tc_hdr_tag::Cb_rt, clip_channel(), convert_YCbCr_to_RGB(), copy_channel(), tc_hdr_tag::Cr_rt, eps_block_header_tag::data_size, tc_hdr_tag::dc_Cb, tc_hdr_tag::dc_Cr, dc_level_unshift(), tc_hdr_tag::dc_Y, EPS_FORMAT_ERROR, EPS_MODE_OTLPF, EPS_OK, EPS_PARAM_ERROR, EPS_RESAMPLE_444, EPS_UNSUPPORTED_FB, extract_channel(), tc_hdr_tag::fb_id, free_2D(), get_block_size(), get_fb(), tc_hdr_tag::h, eps_block_header_tag::hdr_data, eps_block_header_tag::hdr_size, malloc_2D(), tc_hdr_tag::mode, tc_hdr_tag::resample, reset_RGB(), speck_decode(), split_channels(), synthesis_2D(), eps_block_header_tag::tc, unstuff_data(), tc_hdr_tag::w, xmalloc(), and tc_hdr_tag::Y_rt.

int eps_truncate_block ( unsigned char *  buf_in,
unsigned char *  buf_out,
eps_block_header hdr,
int *  truncate_size 
)

Truncate block

This function truncates already encoded GRAYSCALE or TRUECOLOR block. Due to embedded encoding truncation is equivalent to block re-compression.

Parameters:
buf_in Input buffer
buf_out Output buffer
hdr Block header
truncate_size Desired truncated block size
Note:
On successful return, the value pointed by the truncate_size parameter will be overwritten with a real amount of bytes used in the buf_out (it will be less then or equal to the original truncate_size value).

Minimal value for the truncate_size parameter can be calculated as MAX(EPS_MIN_GRAYSCALE_BUF, EPS_MIN_TRUECOLOR_BUF).

Returns:
The function returns either EPS_OK (the block is successfully truncated), or EPS_PARAM_ERROR (one or more parameters are incorrect).

References eps_block_header_tag::data_size, EPS_MIN_GRAYSCALE_BUF, EPS_MIN_TRUECOLOR_BUF, EPS_OK, EPS_PARAM_ERROR, epsilon_crc32(), eps_block_header_tag::hdr_size, MAX, and MIN.


Generated on Fri May 27 14:50:00 2011 for EPSILON by  doxygen 1.5.6