src/lib/openjpwl/jpwl.h

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