jpwl/jpwl.h

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