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 jpwl_marks {
 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         } m;
 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 Encode according to JPWL specs
 210 @param j2k J2K handle
 211 @param cio codestream handle
 212 @param image image handle
 213 */
 214 void jpwl_encode(opj_j2k_t *j2k, opj_cio_t *cio, opj_image_t *image);
 215
 216 /**
 217 Prepare the list of JPWL markers, after the Part 1 codestream
 218 has been finalized (index struct is full)
 219 @param j2k J2K handle
 220 @param cio codestream handle
 221 @param image image handle
 222 */
 223 void jpwl_prepare_marks(opj_j2k_t *j2k, opj_cio_t *cio, opj_image_t *image);
 224
 225 /**
 226 Dump the list of JPWL markers, after it has been prepared
 227 @param j2k J2K handle
 228 @param cio codestream handle
 229 @param image image handle
 230 */
 231 void jpwl_dump_marks(opj_j2k_t *j2k, opj_cio_t *cio, opj_image_t *image);
 232
 233 /**
 234 Read the EPC marker (Error Protection Capability)
 235 @param j2k J2K handle
 236 */
 237 void j2k_read_epc(opj_j2k_t *j2k);
 238
 239 /**
 240 Write the EPC marker (Error Protection Capability), BUT the DL field is always set to 0
 241 (this simplifies the management of EPBs and it is openly stated in the standard
 242 as a possible value, mening that the information is not available) and the informative techniques
 243 are not yet implemented
 244 @param j2k J2K handle
 245 */
 246 void j2k_write_epc(opj_j2k_t *j2k);
 247
 248 /**
 249 Read the EPB marker (Error Protection Block)
 250 @param j2k J2K handle
 251 */
 252 void j2k_read_epb(opj_j2k_t *j2k);
 253
 254 /**
 255 Write the EPB marker (Error Protection Block)
 256 @param j2k J2K handle
 257 */
 258 void j2k_write_epb(opj_j2k_t *j2k);
 259
 260 /**
 261 Read the ESD marker (Error Sensitivity Descriptor)
 262 @param j2k J2K handle
 263 */
 264 void j2k_read_esd(opj_j2k_t *j2k);
 265
 266 /**
 267 Read the RED marker (Residual Error Descriptor)
 268 @param j2k J2K handle
 269 */
 270 void j2k_read_red(opj_j2k_t *j2k);
 271
 272 /** create an EPB marker segment
 273 @param j2k J2K compressor handle
 274 @param latest it is the latest EPB in the header
 275 @param packed EPB is in packed style
 276 @param tileno tile number where the marker has been placed (-1 means MH)
 277 @param idx current EPB running index
 278 @param hprot applied protection type (-1/0,1,16,32,37-128)
 279 @param pre_len length of pre-protected data
 280 @param post_len length of post-protected data
 281 @return returns the freshly created EPB
 282 */
 283 jpwl_epb_ms_t *jpwl_epb_create(opj_j2k_t *j2k, bool latest, bool packed, int tileno, int idx, int hprot,
 284                                                            unsigned long int pre_len, unsigned long int post_len);
 285
 286 /** add a number of EPB marker segments
 287 @param j2k J2K compressor handle
 288 @param jwmarker pointer to the JPWL markers list
 289 @param jwmarker_num pointer to the number of JPWL markers (gets updated)
 290 @param latest it is the latest group of EPBs in the header
 291 @param packed EPBs are in packed style
 292 @param insideMH it is in the MH
 293 @param idx pointer to the starting EPB running index (gets updated)
 294 @param hprot applied protection type (-1/0,1,16,32,37-128)
 295 @param place_pos place in original codestream where EPBs should go
 296 @param tileno tile number of these EPBs
 297 @param pre_len length of pre-protected data
 298 @param post_len length of post-protected data
 299 @return returns the length of all added markers
 300 */
 301 int jpwl_epbs_add(opj_j2k_t *j2k, jpwl_marker_t *jwmarker, int *jwmarker_num,
 302                                   bool latest, bool packed, bool insideMH, int *idx, int hprot,
 303                                   double place_pos, int tileno,
 304                                   unsigned long int pre_len, unsigned long int post_len);
 305
 306 /** add a number of ESD marker segments
 307 @param j2k J2K compressor handle
 308 @param jwmarker pointer to the JPWL markers list
 309 @param jwmarker_num pointer to the number of JPWL markers (gets updated)
 310 @param comps considered component (-1=average, 0/1/2/...=component no.)
 311 @param addrm addressing mode (0=packet, 1=byte range, 2=packet range, 3=reserved)
 312 @param ad_size size of addresses (2/4 bytes)
 313 @param senst sensitivity type
 314 @param se_size sensitivity values size (1/2 bytes)
 315 @param place_pos place in original codestream where EPBs should go
 316 @param tileno tile number of these EPBs
 317 @return returns the length of all added markers
 318 */
 319 int jpwl_esds_add(opj_j2k_t *j2k, jpwl_marker_t *jwmarker, int *jwmarker_num,
 320                                   int comps, unsigned char addrm, unsigned char ad_size,
 321                                   unsigned char senst, unsigned char se_size,
 322                                   double place_pos, int tileno);
 323
 324 /** updates the information structure by modifying the positions and lengths
 325 @param j2k J2K compressor handle
 326 @param jwmarker pointer to JPWL markers list
 327 @param jwmarker_num number of JPWL markers
 328 @return returns true in case of success
 329 */
 330 bool jpwl_update_info(opj_j2k_t *j2k, jpwl_marker_t *jwmarker, int jwmarker_num);
 331
 332
 333 bool jpwl_esd_fill(opj_j2k_t *j2k, jpwl_esd_ms_t *esdmark, unsigned char *buf);
 334
 335 bool jpwl_epb_fill(opj_j2k_t *j2k, jpwl_epb_ms_t *epbmark, unsigned char *buf, unsigned char *post_buf);
 336
 337 void j2k_add_marker(opj_codestream_info_t *cstr_info, unsigned short int type, int pos, int len);
 338
 339 /** corrects the data in the JPWL codestream
 340 @param j2k J2K compressor handle
 341 @return true if correction is performed correctly
 342 */
 343 bool jpwl_correct(opj_j2k_t *j2k);
 344
 345 /** corrects the data protected by an EPB
 346 @param j2k J2K compressor handle
 347 @param buffer pointer to the EPB position
 348 @param type type of EPB: 0=MH, 1=TPH, 2=other, 3=auto
 349 @param pre_len length of pre-data
 350 @param post_len length of post_data
 351 @param conn is a pointer to the length of all connected (packed) EPBs
 352 @param L4_bufp is a pointer to the buffer pointer of redundancy data
 353 @return returns true if correction could be succesfully performed
 354 */
 355 bool jpwl_epb_correct(opj_j2k_t *j2k, unsigned char *buffer, int type, int pre_len, int post_len, int *conn,
 356                                           unsigned char **L4_bufp);
 357
 358 /** check that a tile and its children have valid data
 359 @param j2k J2K decompressor handle
 360 @param tcd Tile decompressor handle
 361 @param tileno number of the tile to check
 362 */
 363 bool jpwl_check_tile(opj_j2k_t *j2k, opj_tcd_t *tcd, int tileno);
 364
 365 /** Macro functions for CRC computation */
 366
 367 /**
 368 Computes the CRC-16, as stated in JPWL specs
 369 @param CRC two bytes containing the CRC value (must be initialized with 0x0000)
 370 @param DATA byte for which the CRC is computed; call this on every byte of the sequence
 371 and get the CRC at the end
 372 */
 373 #define jpwl_updateCRC16(CRC, DATA) updateCRC16(CRC, DATA)
 374
 375 /**
 376 Computes the CRC-32, as stated in JPWL specs
 377 @param CRC four bytes containing the CRC value (must be initialized with 0x00000000)
 378 @param DATA byte for which the CRC is computed; call this on every byte of the sequence
 379 and get the CRC at the end
 380 */
 381 #define jpwl_updateCRC32(CRC, DATA) updateCRC32(CRC, DATA)
 382
 383 /**
 384 Computes the minimum between two integers
 385 @param a first integer to compare
 386 @param b second integer to compare
 387 @return returns the minimum integer between a and b
 388 */
 389 #ifndef min
 390 #define min(a,b)    (((a) < (b)) ? (a) : (b))
 391 #endif /* min */
 392
 393 /*@}*/
 394
 395 #endif /* USE_JPWL */
 396
 397 #ifdef USE_JPSEC
 398
 399 /** @defgroup JPSEC JPSEC - JPEG-2000 Part 8 (JPSEC) codestream manager */
 400 /*@{*/
 401
 402 /**
 403 Read the SEC marker (SEcured Codestream)
 404 @param j2k J2K handle
 405 */
 406 void j2k_read_sec(opj_j2k_t *j2k);
 407
 408 /**
 409 Write the SEC marker (SEcured Codestream)
 410 @param j2k J2K handle
 411 */
 412 void j2k_write_sec(opj_j2k_t *j2k);
 413
 414 /**
 415 Read the INSEC marker (SEcured Codestream)
 416 @param j2k J2K handle
 417 */
 418 void j2k_read_insec(opj_j2k_t *j2k);
 419
 420 /*@}*/
 421
 422 #endif /* USE_JPSEC */
 423
 424 #endif /* __JPWL_H */
 425