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