jpwl/jpwl.h

   1 /*\r
   2  * Copyright (c) 2001-2003, David Janssens\r
   3  * Copyright (c) 2002-2003, Yannick Verschueren\r
   4  * Copyright (c) 2003-2005, Francois Devaux and Antonin Descampe\r
   5  * Copyright (c) 2005, Herv� Drolon, FreeImage Team\r
   6  * Copyright (c) 2002-2005, Communications and remote sensing Laboratory, Universite catholique de Louvain, Belgium\r
   7  * Copyright (c) 2005-2006, Dept. of Electronic and Information Engineering, Universita' degli Studi di Perugia, Italy\r
   8  * All rights reserved.\r
   9  *\r
  10  * Redistribution and use in source and binary forms, with or without\r
  11  * modification, are permitted provided that the following conditions\r
  12  * are met:\r
  13  * 1. Redistributions of source code must retain the above copyright\r
  14  *    notice, this list of conditions and the following disclaimer.\r
  15  * 2. Redistributions in binary form must reproduce the above copyright\r
  16  *    notice, this list of conditions and the following disclaimer in the\r
  17  *    documentation and/or other materials provided with the distribution.\r
  18  *\r
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'\r
  20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\r
  21  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\r
  22  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE\r
  23  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR\r
  24  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF\r
  25  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS\r
  26  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN\r
  27  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)\r
  28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\r
  29  * POSSIBILITY OF SUCH DAMAGE.\r
  30  */\r
  31 #ifndef __JPWL_H\r
  32 #define __JPWL_H\r
  33 \r
  34 #ifdef USE_JPWL\r
  35 \r
  36 #include "crc.h"\r
  37 #include "rs.h"\r
  38 \r
  39 /**\r
  40 @file jpwl.h\r
  41 @brief The JPEG-2000 Part11 (JPWL) marker segments manager\r
  42 \r
  43 The functions in JPWL.C have for goal to read/write the markers added by JPWL.\r
  44 */\r
  45 \r
  46 /** @defgroup JPWL JPWL - JPEG-2000 Part11 (JPWL) codestream manager */\r
  47 /*@{*/\r
  48 \r
  49 /**\r
  50 Assume a basic codestream structure, so you can resort better from uncorrected errors\r
  51 */\r
  52 #define JPWL_ASSUME true\r
  53 \r
  54 /**\r
  55 EPB (Error Protection Block) Marker segment\r
  56 */\r
  57 typedef struct jpwl_epb_ms {\r
  58         /**@name Private fields set by epb_create */\r
  59         /*@{*/\r
  60         /** is the latest in header? */\r
  61         bool latest;\r
  62         /** is it in packed mode? */\r
  63         bool packed;\r
  64         /** TH where this marker has been placed (-1 means MH) */\r
  65         int tileno;\r
  66         /** index in current header (0-63) */\r
  67         unsigned char index;\r
  68         /** error protection method     [-1=absent 0=none 1=predefined 16=CRC-16 32=CRC-32 37-128=RS] */\r
  69         int hprot;\r
  70         /** message word length of pre-data */\r
  71         int k_pre;\r
  72         /** code word length of pre-data */\r
  73         int n_pre;\r
  74         /** length of pre-data */\r
  75         int pre_len;\r
  76         /** message word length of post-data */\r
  77         int k_post;\r
  78         /** code word length of post-data */\r
  79         int n_post;\r
  80         /** length of post-data */\r
  81         int post_len;\r
  82         /*@}*/\r
  83         /**@name Marker segment fields */\r
  84         /*@{*/\r
  85         /** two bytes for the length of EPB MS, exluding the marker itself (11 to 65535 bytes) */\r
  86         unsigned short int Lepb;\r
  87         /** single byte for the style */\r
  88         unsigned char Depb; \r
  89         /** four bytes, from 0 to 2^31-1 */\r
  90         unsigned long int LDPepb;\r
  91         /** four bytes, next error management method */\r
  92         unsigned long int Pepb;\r
  93         /** EPB data, variable size */\r
  94         unsigned char *data;   \r
  95         /*@}*/\r
  96 }       jpwl_epb_ms_t;\r
  97 \r
  98 /**\r
  99 EPC (Error Protection Capability) Marker segment\r
 100 */\r
 101 typedef struct jpwl_epc_ms {\r
 102         /** is ESD active? */\r
 103         bool esd_on;\r
 104         /** is RED active? */\r
 105         bool red_on;\r
 106         /** is EPB active? */\r
 107         bool epb_on;\r
 108         /** are informative techniques active? */\r
 109         bool info_on;\r
 110         /**@name Marker segment fields */\r
 111         /*@{*/\r
 112         /** two bytes for the length of EPC MS, exluding the marker itself (9 to 65535 bytes) */\r
 113         unsigned short int Lepc;   \r
 114         /** two bytes, CRC for the EPC, excluding Pcrc itself */\r
 115         unsigned short int Pcrc;   \r
 116         /** four bytes, the codestream length from SOC to EOC */\r
 117         unsigned long int DL;     \r
 118         /** one byte, signals JPWL techniques adoption */\r
 119         unsigned char Pepc;     \r
 120         /** EPC data, variable length */\r
 121         unsigned char *data;    \r
 122         /*@}*/\r
 123 }       jpwl_epc_ms_t;\r
 124 \r
 125 /**\r
 126 ESD (Error Sensitivity Descriptor) Marker segment\r
 127 */\r
 128 typedef struct jpwl_esd_ms {\r
 129         /** codestream addressing mode [0=packet, 1=byte range, 2=packet range, 3=reserved] */\r
 130         unsigned char addrm;\r
 131         /** size of codestream addresses [2/4 bytes] */\r
 132         unsigned char ad_size;\r
 133         /** type of sensitivity\r
 134         [0=relative error, 1=MSE, 2=MSE reduction, 3=PSNR, 4=PSNR increment,\r
 135         5=MAXERR (absolute peak error), 6=TSE (total squared error), 7=reserved */\r
 136         unsigned char senst;\r
 137         /** size of sensitivity data (1/2 bytes) */\r
 138         unsigned char se_size;\r
 139         /**@name Marker segment fields */\r
 140         /*@{*/\r
 141         /** two bytes for the length of ESD MS, exluding the marker itself (4 to 65535 bytes) */\r
 142         unsigned short int Lesd;   \r
 143         /** two bytes, component of error sensitivity */\r
 144         unsigned short int Cesd;\r
 145         /** one byte, signals JPWL techniques adoption */\r
 146         unsigned char Pesd;     \r
 147         /** ESD data, variable length */\r
 148         unsigned char *data;    \r
 149         /*@}*/\r
 150         /**@name Fields set by esd_create (only internal use) */\r
 151         /*@{*/\r
 152         /** number of components in the image */\r
 153         int numcomps;\r
 154         /** tile where this marker has been placed (-1 means MH) */\r
 155         int tileno;\r
 156         /** number of sensitivity values */\r
 157         unsigned long int svalnum;\r
 158         /** size of a single sensitivity pair (address+value) */\r
 159         size_t sensval_size;\r
 160         /*@}*/\r
 161 }       jpwl_esd_ms_t;\r
 162 \r
 163 /**\r
 164 RED (Residual Error Descriptor) Marker segment\r
 165 */\r
 166 typedef struct jpwl_red_ms {\r
 167         /** two bytes for the length of RED MS, exluding the marker itself (3 to 65535 bytes) */\r
 168         unsigned short int Lred;\r
 169         /** one byte, signals JPWL techniques adoption */\r
 170         unsigned char Pred;     \r
 171         /** RED data, variable length */\r
 172         unsigned char *data;    \r
 173 }       jpwl_red_ms_t;\r
 174 \r
 175 /**\r
 176 Structure used to store JPWL markers temporary position and readyness\r
 177 */\r
 178 typedef struct jpwl_marker {\r
 179         /** marker value (J2K_MS_EPC, etc.) */\r
 180         int id;\r
 181         /** union keeping the pointer to the real marker struct */\r
 182         union {\r
 183                 /** pointer to EPB marker */\r
 184                 jpwl_epb_ms_t *epbmark;\r
 185                 /** pointer to EPC marker */\r
 186                 jpwl_epc_ms_t *epcmark;\r
 187                 /** pointer to ESD marker */\r
 188                 jpwl_esd_ms_t *esdmark;\r
 189                 /** pointer to RED marker */\r
 190                 jpwl_red_ms_t *redmark;\r
 191         };\r
 192         /** position where the marker should go, in the pre-JPWL codestream */ \r
 193         unsigned long int pos;\r
 194         /** same as before, only written as a double, so we can sort it better */\r
 195         double dpos;\r
 196         /** length of the marker segment (marker excluded) */\r
 197         unsigned short int len;\r
 198         /** the marker length is ready or not? */\r
 199         bool len_ready;\r
 200         /** the marker position is ready or not? */\r
 201         bool pos_ready;\r
 202         /** the marker parameters are ready or not? */\r
 203         bool parms_ready;\r
 204         /** are the written data ready or not */\r
 205         bool data_ready;\r
 206 }       jpwl_marker_t;\r
 207 \r
 208 /**\r
 209 Prepare the list of JPWL markers, after the Part 1 codestream\r
 210 has been finalized (index struct is full)\r
 211 @param j2k J2K handle\r
 212 @param cio codestream handle\r
 213 @param image image handle\r
 214 */\r
 215 void jpwl_prepare_marks(opj_j2k_t *j2k, opj_cio_t *cio, opj_image_t *image);\r
 216 \r
 217 /**\r
 218 Dump the list of JPWL markers, after it has been prepared\r
 219 @param j2k J2K handle\r
 220 @param cio codestream handle\r
 221 @param image image handle\r
 222 */\r
 223 void jpwl_dump_marks(opj_j2k_t *j2k, opj_cio_t *cio, opj_image_t *image);\r
 224 \r
 225 /**\r
 226 Read the EPC marker (Error Protection Capability)\r
 227 @param j2k J2K handle\r
 228 */\r
 229 void j2k_read_epc(opj_j2k_t *j2k);\r
 230 /**\r
 231 Write the EPC marker (Error Protection Capability), BUT the DL field is always set to 0\r
 232 (this simplifies the management of EPBs and it is openly stated in the standard\r
 233 as a possible value, mening that the information is not available) and the informative techniques\r
 234 are not yet implemented\r
 235 @param j2k J2K handle\r
 236 */\r
 237 void j2k_write_epc(opj_j2k_t *j2k);\r
 238 /**\r
 239 Read the EPB marker (Error Protection Block)\r
 240 @param j2k J2K handle\r
 241 */\r
 242 void j2k_read_epb(opj_j2k_t *j2k);\r
 243 /**\r
 244 Write the EPB marker (Error Protection Block)\r
 245 @param j2k J2K handle\r
 246 */\r
 247 void j2k_write_epb(opj_j2k_t *j2k);\r
 248 /**\r
 249 Read the ESD marker (Error Sensitivity Descriptor)\r
 250 @param j2k J2K handle\r
 251 */\r
 252 void j2k_read_esd(opj_j2k_t *j2k);\r
 253 /**\r
 254 Read the RED marker (Residual Error Descriptor)\r
 255 @param j2k J2K handle\r
 256 */\r
 257 void j2k_read_red(opj_j2k_t *j2k);\r
 258 \r
 259 /** create an EPB marker segment\r
 260 @param j2k J2K compressor handle\r
 261 @param latest it is the latest EPB in the header\r
 262 @param packed EPB is in packed style\r
 263 @param tileno tile number where the marker has been placed (-1 means MH)\r
 264 @param idx current EPB running index\r
 265 @param hprot applied protection type (-1/0,1,16,32,37-128)\r
 266 @param pre_len length of pre-protected data\r
 267 @param post_len length of post-protected data\r
 268 @return returns the freshly created EPB\r
 269 */\r
 270 jpwl_epb_ms_t *jpwl_epb_create(opj_j2k_t *j2k, bool latest, bool packed, int tileno, int idx, int hprot,\r
 271                                                            unsigned long int pre_len, unsigned long int post_len);\r
 272 \r
 273 /** add a number of EPB marker segments\r
 274 @param j2k J2K compressor handle\r
 275 @param jwmarker pointer to the JPWL markers list\r
 276 @param jwmarker_num pointer to the number of JPWL markers (gets updated)\r
 277 @param latest it is the latest group of EPBs in the header\r
 278 @param packed EPBs are in packed style\r
 279 @param insideMH it is in the MH\r
 280 @param idx pointer to the starting EPB running index (gets updated)\r
 281 @param hprot applied protection type (-1/0,1,16,32,37-128)\r
 282 @param place_pos place in original codestream where EPBs should go\r
 283 @param tileno tile number of these EPBs\r
 284 @param pre_len length of pre-protected data\r
 285 @param post_len length of post-protected data\r
 286 @return returns the length of all added markers\r
 287 */\r
 288 int jpwl_epbs_add(opj_j2k_t *j2k, jpwl_marker_t *jwmarker, int *jwmarker_num,\r
 289                                   bool latest, bool packed, bool insideMH, int *idx, int hprot,\r
 290                                   double place_pos, int tileno,\r
 291                                   unsigned long int pre_len, unsigned long int post_len);\r
 292 \r
 293 /** add a number of ESD marker segments\r
 294 @param j2k J2K compressor handle\r
 295 @param jwmarker pointer to the JPWL markers list\r
 296 @param jwmarker_num pointer to the number of JPWL markers (gets updated)\r
 297 @param comps considered component (-1=average, 0/1/2/...=component no.)\r
 298 @param addrm addressing mode (0=packet, 1=byte range, 2=packet range, 3=reserved)\r
 299 @param ad_size size of addresses (2/4 bytes)\r
 300 @param senst sensitivity type\r
 301 @param se_size sensitivity values size (1/2 bytes)\r
 302 @param place_pos place in original codestream where EPBs should go\r
 303 @param tileno tile number of these EPBs\r
 304 @return returns the length of all added markers\r
 305 */\r
 306 int jpwl_esds_add(opj_j2k_t *j2k, jpwl_marker_t *jwmarker, int *jwmarker_num,\r
 307                                   int comps, unsigned char addrm, unsigned char ad_size,\r
 308                                   unsigned char senst, unsigned char se_size,\r
 309                                   double place_pos, int tileno);\r
 310         \r
 311 /** updates the information structure by modifying the positions and lengths\r
 312 @param j2k J2K compressor handle\r
 313 @param jwmarker pointer to JPWL markers list\r
 314 @param jwmarker_num number of JPWL markers\r
 315 @return returns true in case of success\r
 316 */                        \r
 317 bool jpwl_update_info(opj_j2k_t *j2k, jpwl_marker_t *jwmarker, int jwmarker_num);\r
 318 \r
 319 \r
 320 bool jpwl_esd_fill(opj_j2k_t *j2k, jpwl_esd_ms_t *esdmark, unsigned char *buf);\r
 321 \r
 322 bool jpwl_epb_fill(opj_j2k_t *j2k, jpwl_epb_ms_t *epbmark, unsigned char *buf, unsigned char *post_buf);\r
 323 \r
 324 /** corrects the data in the JPWL codestream\r
 325 @param j2k J2K compressor handle\r
 326 @return true if correction is performed correctly\r
 327 */\r
 328 bool jpwl_correct(opj_j2k_t *j2k);\r
 329 \r
 330 /** corrects the data protected by an EPB\r
 331 @param j2k J2K compressor handle\r
 332 @param buffer pointer to the EPB position\r
 333 @param type type of EPB: 0=MH, 1=TPH, 2=other, 3=auto\r
 334 @param pre_len length of pre-data\r
 335 @param post_len length of post_data\r
 336 @param conn is a pointer to the length of all connected (packed) EPBs\r
 337 @param L4_bufp is a pointer to the buffer pointer of redundancy data\r
 338 @return returns true if correction could be succesfully performed\r
 339 */\r
 340 bool jpwl_epb_correct(opj_j2k_t *j2k, unsigned char *buffer, int type, int pre_len, int post_len, int *conn,\r
 341                                           unsigned char **L4_bufp);\r
 342 \r
 343 /** check that a tile and its children have valid data\r
 344 @param j2k J2K decompressor handle\r
 345 @param tcd Tile decompressor handle\r
 346 @param tileno number of the tile to check\r
 347 */\r
 348 bool jpwl_check_tile(opj_j2k_t *j2k, opj_tcd_t *tcd, int tileno);\r
 349 \r
 350 /** Macro functions for CRC computation */\r
 351 \r
 352 /**\r
 353 Computes the CRC-16, as stated in JPWL specs\r
 354 @param CRC two bytes containing the CRC value (must be initialized with 0x0000)\r
 355 @param DATA byte for which the CRC is computed; call this on every byte of the sequence\r
 356 and get the CRC at the end\r
 357 */\r
 358 #define jpwl_updateCRC16(CRC, DATA) updateCRC16(CRC, DATA)\r
 359 \r
 360 /**\r
 361 Computes the CRC-32, as stated in JPWL specs\r
 362 @param CRC four bytes containing the CRC value (must be initialized with 0x00000000)\r
 363 @param DATA byte for which the CRC is computed; call this on every byte of the sequence\r
 364 and get the CRC at the end\r
 365 */\r
 366 #define jpwl_updateCRC32(CRC, DATA) updateCRC32(CRC, DATA)\r
 367 \r
 368 /*@}*/\r
 369 \r
 370 #endif /* USE_JPWL */\r
 371 \r
 372 #endif /* __JPWL_H */\r