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,
 291                                int tileno, int idx, int hprot,
 292                                unsigned long int pre_len, unsigned long int post_len);
 293
 294 /** add a number of EPB marker segments
 295 @param j2k J2K compressor handle
 296 @param jwmarker pointer to the JPWL markers list
 297 @param jwmarker_num pointer to the number of JPWL markers (gets updated)
 298 @param latest it is the latest group of EPBs in the header
 299 @param packed EPBs are in packed style
 300 @param insideMH it is in the MH
 301 @param idx pointer to the starting EPB running index (gets updated)
 302 @param hprot applied protection type (-1/0,1,16,32,37-128)
 303 @param place_pos place in original codestream where EPBs should go
 304 @param tileno tile number of these EPBs
 305 @param pre_len length of pre-protected data
 306 @param post_len length of post-protected data
 307 @return returns the length of all added markers
 308 */
 309 int jpwl_epbs_add(opj_j2k_t *j2k, jpwl_marker_t *jwmarker, int *jwmarker_num,
 310                   opj_bool latest, opj_bool packed, opj_bool insideMH, int *idx, int hprot,
 311                   double place_pos, int tileno,
 312                   unsigned long int pre_len, unsigned long int post_len);
 313
 314 /** add a number of ESD marker segments
 315 @param j2k J2K compressor handle
 316 @param jwmarker pointer to the JPWL markers list
 317 @param jwmarker_num pointer to the number of JPWL markers (gets updated)
 318 @param comps considered component (-1=average, 0/1/2/...=component no.)
 319 @param addrm addressing mode (0=packet, 1=byte range, 2=packet range, 3=reserved)
 320 @param ad_size size of addresses (2/4 bytes)
 321 @param senst sensitivity type
 322 @param se_size sensitivity values size (1/2 bytes)
 323 @param place_pos place in original codestream where EPBs should go
 324 @param tileno tile number of these EPBs
 325 @return returns the length of all added markers
 326 */
 327 int jpwl_esds_add(opj_j2k_t *j2k, jpwl_marker_t *jwmarker, int *jwmarker_num,
 328                   int comps, unsigned char addrm, unsigned char ad_size,
 329                   unsigned char senst, unsigned char se_size,
 330                   double place_pos, int tileno);
 331
 332 /** updates the information structure by modifying the positions and lengths
 333 @param j2k J2K compressor handle
 334 @param jwmarker pointer to JPWL markers list
 335 @param jwmarker_num number of JPWL markers
 336 @return returns true in case of success
 337 */
 338 opj_bool jpwl_update_info(opj_j2k_t *j2k, jpwl_marker_t *jwmarker,
 339                           int jwmarker_num);
 340
 341
 342 opj_bool jpwl_esd_fill(opj_j2k_t *j2k, jpwl_esd_ms_t *esdmark,
 343                        unsigned char *buf);
 344
 345 opj_bool jpwl_epb_fill(opj_j2k_t *j2k, jpwl_epb_ms_t *epbmark,
 346                        unsigned char *buf, unsigned char *post_buf);
 347
 348 opj_bool j2k_add_marker(opj_codestream_info_t *cstr_info,
 349                         unsigned short int type, int pos, int len);
 350
 351 /** corrects the data in the JPWL codestream
 352 @param j2k J2K compressor handle
 353 @return true if correction is performed correctly
 354 */
 355 opj_bool jpwl_correct(opj_j2k_t *j2k);
 356
 357 /** corrects the data protected by an EPB
 358 @param j2k J2K compressor handle
 359 @param buffer pointer to the EPB position
 360 @param type type of EPB: 0=MH, 1=TPH, 2=other, 3=auto
 361 @param pre_len length of pre-data
 362 @param post_len length of post_data
 363 @param conn is a pointer to the length of all connected (packed) EPBs
 364 @param L4_bufp is a pointer to the buffer pointer of redundancy data
 365 @return returns true if correction could be successfully performed
 366 */
 367 opj_bool jpwl_epb_correct(opj_j2k_t *j2k, unsigned char *buffer, int type,
 368                           int pre_len, int post_len, int *conn,
 369                           unsigned char **L4_bufp);
 370
 371 /** check that a tile and its children have valid data
 372 @param j2k J2K decompressor handle
 373 @param tcd Tile decompressor handle
 374 @param tileno number of the tile to check
 375 */
 376 opj_bool jpwl_check_tile(opj_j2k_t *j2k, opj_tcd_t *tcd, int tileno);
 377
 378 /** Macro functions for CRC computation */
 379
 380 /**
 381 Computes the CRC-16, as stated in JPWL specs
 382 @param CRC two bytes containing the CRC value (must be initialized with 0x0000)
 383 @param DATA byte for which the CRC is computed; call this on every byte of the sequence
 384 and get the CRC at the end
 385 */
 386 #define jpwl_updateCRC16(CRC, DATA) updateCRC16(CRC, DATA)
 387
 388 /**
 389 Computes the CRC-32, as stated in JPWL specs
 390 @param CRC four bytes containing the CRC value (must be initialized with 0x00000000)
 391 @param DATA byte for which the CRC is computed; call this on every byte of the sequence
 392 and get the CRC at the end
 393 */
 394 #define jpwl_updateCRC32(CRC, DATA) updateCRC32(CRC, DATA)
 395
 396 /**
 397 Computes the minimum between two integers
 398 @param a first integer to compare
 399 @param b second integer to compare
 400 @return returns the minimum integer between a and b
 401 */
 402 #ifndef min
 403 #define min(a,b)    (((a) < (b)) ? (a) : (b))
 404 #endif /* min */
 405
 406 /*@}*/
 407
 408 #endif /* USE_JPWL */
 409
 410 #ifdef USE_JPSEC
 411
 412 /** @defgroup JPSEC JPSEC - JPEG-2000 Part 8 (JPSEC) codestream manager */
 413 /*@{*/
 414
 415 /**
 416 Read the SEC marker (SEcured Codestream)
 417 @param j2k J2K handle
 418 */
 419 void j2k_read_sec(opj_j2k_t *j2k);
 420
 421 /**
 422 Write the SEC marker (SEcured Codestream)
 423 @param j2k J2K handle
 424 */
 425 void j2k_write_sec(opj_j2k_t *j2k);
 426
 427 /**
 428 Read the INSEC marker (SEcured Codestream)
 429 @param j2k J2K handle
 430 */
 431 void j2k_read_insec(opj_j2k_t *j2k);
 432
 433 /*@}*/
 434
 435 #endif /* USE_JPSEC */
 436
 437 #endif /* __JPWL_H */
 438