src/lib/openjp2/mqc.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) 2002-2014, Universite catholique de Louvain (UCL), Belgium
   8  * Copyright (c) 2002-2014, Professor Benoit Macq
   9  * Copyright (c) 2001-2003, David Janssens
  10  * Copyright (c) 2002-2003, Yannick Verschueren
  11  * Copyright (c) 2003-2007, Francois-Olivier Devaux
  12  * Copyright (c) 2003-2014, Antonin Descampe
  13  * Copyright (c) 2005, Herve Drolon, FreeImage Team
  14  * Copyright (c) 2008, Jerome Fimes, Communications & Systemes <jerome.fimes@c-s.fr>
  15  * All rights reserved.
  16  *
  17  * Redistribution and use in source and binary forms, with or without
  18  * modification, are permitted provided that the following conditions
  19  * are met:
  20  * 1. Redistributions of source code must retain the above copyright
  21  *    notice, this list of conditions and the following disclaimer.
  22  * 2. Redistributions in binary form must reproduce the above copyright
  23  *    notice, this list of conditions and the following disclaimer in the
  24  *    documentation and/or other materials provided with the distribution.
  25  *
  26  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  27  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  28  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  29  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  30  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  31  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  32  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  33  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  34  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  35  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  36  * POSSIBILITY OF SUCH DAMAGE.
  37  */
  38
  39 #ifndef __MQC_H
  40 #define __MQC_H
  41
  42 #include "opj_common.h"
  43
  44 /**
  45 @file mqc.h
  46 @brief Implementation of an MQ-Coder (MQC)
  47
  48 The functions in MQC.C have for goal to realize the MQ-coder operations. The functions
  49 in MQC.C are used by some function in T1.C.
  50 */
  51
  52 /** @defgroup MQC MQC - Implementation of an MQ-Coder */
  53 /*@{*/
  54
  55 /**
  56 This struct defines the state of a context.
  57 */
  58 typedef struct opj_mqc_state {
  59     /** the probability of the Least Probable Symbol (0.75->0x8000, 1.5->0xffff) */
  60     OPJ_UINT32 qeval;
  61     /** the Most Probable Symbol (0 or 1) */
  62     OPJ_UINT32 mps;
  63     /** next state if the next encoded symbol is the MPS */
  64     struct opj_mqc_state *nmps;
  65     /** next state if the next encoded symbol is the LPS */
  66     struct opj_mqc_state *nlps;
  67 } opj_mqc_state_t;
  68
  69 #define MQC_NUMCTXS 19
  70
  71 /**
  72 MQ coder
  73 */
  74 typedef struct opj_mqc {
  75     /** temporary buffer where bits are coded or decoded */
  76     OPJ_UINT32 c;
  77     /** only used by MQ decoder */
  78     OPJ_UINT32 a;
  79     /** number of bits already read or free to write */
  80     OPJ_UINT32 ct;
  81     /** pointer to the current position in the buffer */
  82     OPJ_BYTE *bp;
  83     /** pointer to the start of the buffer */
  84     OPJ_BYTE *start;
  85     /** pointer to the end of the buffer */
  86     OPJ_BYTE *end;
  87     /** Array of contexts */
  88     opj_mqc_state_t *ctxs[MQC_NUMCTXS];
  89     /** Active context */
  90     opj_mqc_state_t **curctx;
  91     /* lut_ctxno_zc shifted by (1 << 9) * bandno */
  92     const OPJ_BYTE* lut_ctxno_zc_orient;
  93     /** Original value of the 2 bytes at end[0] and end[1] */
  94     OPJ_BYTE backup[OPJ_COMMON_CBLK_DATA_EXTRA];
  95 } opj_mqc_t;
  96
  97 #include "mqc_inl.h"
  98
  99 /** @name Exported functions */
 100 /*@{*/
 101 /* ----------------------------------------------------------------------- */
 102
 103 /**
 104 Return the number of bytes written/read since initialisation
 105 @param mqc MQC handle
 106 @return Returns the number of bytes already encoded
 107 */
 108 OPJ_UINT32 opj_mqc_numbytes(opj_mqc_t *mqc);
 109 /**
 110 Reset the states of all the context of the coder/decoder
 111 (each context is set to a state where 0 and 1 are more or less equiprobable)
 112 @param mqc MQC handle
 113 */
 114 void opj_mqc_resetstates(opj_mqc_t *mqc);
 115 /**
 116 Set the state of a particular context
 117 @param mqc MQC handle
 118 @param ctxno Number that identifies the context
 119 @param msb The MSB of the new state of the context
 120 @param prob Number that identifies the probability of the symbols for the new state of the context
 121 */
 122 void opj_mqc_setstate(opj_mqc_t *mqc, OPJ_UINT32 ctxno, OPJ_UINT32 msb,
 123                       OPJ_INT32 prob);
 124 /**
 125 Initialize the encoder
 126 @param mqc MQC handle
 127 @param bp Pointer to the start of the buffer where the bytes will be written
 128 */
 129 void opj_mqc_init_enc(opj_mqc_t *mqc, OPJ_BYTE *bp);
 130 /**
 131 Set the current context used for coding/decoding
 132 @param mqc MQC handle
 133 @param ctxno Number that identifies the context
 134 */
 135 #define opj_mqc_setcurctx(mqc, ctxno)   (mqc)->curctx = &(mqc)->ctxs[(OPJ_UINT32)(ctxno)]
 136 /**
 137 Encode a symbol using the MQ-coder
 138 @param mqc MQC handle
 139 @param d The symbol to be encoded (0 or 1)
 140 */
 141 void opj_mqc_encode(opj_mqc_t *mqc, OPJ_UINT32 d);
 142 /**
 143 Flush the encoder, so that all remaining data is written
 144 @param mqc MQC handle
 145 */
 146 void opj_mqc_flush(opj_mqc_t *mqc);
 147 /**
 148 BYPASS mode switch, initialization operation.
 149 JPEG 2000 p 505.
 150 @param mqc MQC handle
 151 */
 152 void opj_mqc_bypass_init_enc(opj_mqc_t *mqc);
 153
 154 /** Return number of extra bytes to add to opj_mqc_numbytes() for the²
 155     size of a non-terminating BYPASS pass
 156 @param mqc MQC handle
 157 @param erterm 1 if ERTERM is enabled, 0 otherwise
 158 */
 159 OPJ_UINT32 opj_mqc_bypass_get_extra_bytes(opj_mqc_t *mqc, OPJ_BOOL erterm);
 160
 161 /**
 162 BYPASS mode switch, coding operation.
 163 JPEG 2000 p 505.
 164 @param mqc MQC handle
 165 @param d The symbol to be encoded (0 or 1)
 166 */
 167 void opj_mqc_bypass_enc(opj_mqc_t *mqc, OPJ_UINT32 d);
 168 /**
 169 BYPASS mode switch, flush operation
 170 @param mqc MQC handle
 171 @param erterm 1 if ERTERM is enabled, 0 otherwise
 172 */
 173 void opj_mqc_bypass_flush_enc(opj_mqc_t *mqc, OPJ_BOOL erterm);
 174 /**
 175 RESET mode switch
 176 @param mqc MQC handle
 177 */
 178 void opj_mqc_reset_enc(opj_mqc_t *mqc);
 179
 180 #ifdef notdef
 181 /**
 182 RESTART mode switch (TERMALL)
 183 @param mqc MQC handle
 184 @return Returns 1 (always)
 185 */
 186 OPJ_UINT32 opj_mqc_restart_enc(opj_mqc_t *mqc);
 187 #endif
 188
 189 /**
 190 RESTART mode switch (TERMALL) reinitialisation
 191 @param mqc MQC handle
 192 */
 193 void opj_mqc_restart_init_enc(opj_mqc_t *mqc);
 194 /**
 195 ERTERM mode switch (PTERM)
 196 @param mqc MQC handle
 197 */
 198 void opj_mqc_erterm_enc(opj_mqc_t *mqc);
 199 /**
 200 SEGMARK mode switch (SEGSYM)
 201 @param mqc MQC handle
 202 */
 203 void opj_mqc_segmark_enc(opj_mqc_t *mqc);
 204
 205 /**
 206 Initialize the decoder for MQ decoding.
 207
 208 opj_mqc_finish_dec() must be absolutely called after finishing the decoding
 209 passes, so as to restore the bytes temporarily overwritten.
 210
 211 @param mqc MQC handle
 212 @param bp Pointer to the start of the buffer from which the bytes will be read
 213           Note that OPJ_COMMON_CBLK_DATA_EXTRA bytes at the end of the buffer
 214           will be temporarily overwritten with an artificial 0xFF 0xFF marker.
 215           (they will be backuped in the mqc structure to be restored later)
 216           So bp must be at least len + OPJ_COMMON_CBLK_DATA_EXTRA large, and
 217           writable.
 218 @param len Length of the input buffer
 219 @param extra_writable_bytes Indicate how many bytes after len are writable.
 220                             This is to indicate your consent that bp must be
 221                             large enough.
 222 */
 223 void opj_mqc_init_dec(opj_mqc_t *mqc, OPJ_BYTE *bp, OPJ_UINT32 len,
 224                       OPJ_UINT32 extra_writable_bytes);
 225
 226 /**
 227 Initialize the decoder for RAW decoding.
 228
 229 opj_mqc_finish_dec() must be absolutely called after finishing the decoding
 230 passes, so as to restore the bytes temporarily overwritten.
 231
 232 @param mqc MQC handle
 233 @param bp Pointer to the start of the buffer from which the bytes will be read
 234           Note that OPJ_COMMON_CBLK_DATA_EXTRA bytes at the end of the buffer
 235           will be temporarily overwritten with an artificial 0xFF 0xFF marker.
 236           (they will be backuped in the mqc structure to be restored later)
 237           So bp must be at least len + OPJ_COMMON_CBLK_DATA_EXTRA large, and
 238           writable.
 239 @param len Length of the input buffer
 240 @param extra_writable_bytes Indicate how many bytes after len are writable.
 241                             This is to indicate your consent that bp must be
 242                             large enough.
 243 */
 244 void opj_mqc_raw_init_dec(opj_mqc_t *mqc, OPJ_BYTE *bp, OPJ_UINT32 len,
 245                           OPJ_UINT32 extra_writable_bytes);
 246
 247
 248 /**
 249 Terminate RAW/MQC decoding
 250
 251 This restores the bytes temporarily overwritten by opj_mqc_init_dec()/
 252 opj_mqc_raw_init_dec()
 253
 254 @param mqc MQC handle
 255 */
 256 void opq_mqc_finish_dec(opj_mqc_t *mqc);
 257
 258 /**
 259 Decode a symbol
 260 @param mqc MQC handle
 261 @return Returns the decoded symbol (0 or 1)
 262 */
 263 /*static INLINE OPJ_UINT32 opj_mqc_decode(opj_mqc_t * const mqc);*/
 264 /* ----------------------------------------------------------------------- */
 265 /*@}*/
 266
 267 /*@}*/
 268
 269 #endif /* __MQC_H */