nanocoat/include/sjme/bitStream.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Bit streams, used to read data at the bit level rather than byte level.
  12  *
  13  * @since 2024/08/25
  14  */
  15
  16 #ifndef SQUIRRELJME_BITSTREAM_H
  17 #define SQUIRRELJME_BITSTREAM_H
  18
  19 #include "sjme/stdTypes.h"
  20 #include "sjme/closeable.h"
  21 #include "sjme/stream.h"
  22
  23 /* Anti-C++. */
  24 #ifdef __cplusplus
  25         #ifndef SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_SQUIRRELJME_BITSTREAM_H
  28 extern "C"
  29 {
  30         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  31 #endif /* #ifdef __cplusplus */
  32
  33 /*--------------------------------------------------------------------------*/
  34
  35 /**
  36  * Order for when reading or writing multiple bits.
  37  *
  38  * @since 2024/08/28
  39  */
  40 typedef enum sjme_bitStream_order
  41 {
  42         /** Least significant bit. */
  43         SJME_BITSTREAM_LSB,
  44
  45         /** Most significant bit. */
  46         SJME_BITSTREAM_MSB,
  47 } sjme_bitStream_order;
  48
  49 /**
  50  * Bit stream state structure, generic.
  51  *
  52  * @since 2024/08/26
  53  */
  54 typedef struct sjme_bitStream_base
  55 {
  56         /** Closeable data, as bit streams may be closed. */
  57         sjme_closeableBase closeable;
  58
  59         /** The closeable to close, if forwarded, optional. */
  60         sjme_closeable forwardClose;
  61
  62         /** Pointer to pass to the function as data. */
  63         sjme_pointer funcData;
  64
  65         /** The number of bits read/written. */
  66         sjme_juint streamCount;
  67
  68         /** The current bit queue. */
  69         sjme_juint bitQueue;
  70
  71         /** The amount of bits in the buffer. */
  72         sjme_juint bitCount;
  73
  74         /** Overflow bits. */
  75         sjme_juint overQueue;
  76
  77         /** The overflow count. */
  78         sjme_juint overCount;
  79 } sjme_bitStream_base;
  80
  81 /**
  82  * Base bitstream type.
  83  *
  84  * @since 2024/08/31
  85  */
  86 typedef sjme_bitStream_base* sjme_bitStream;
  87
  88 /** Cast to a bit stream base. */
  89 #define SJME_AS_BITSTREAM(x) ((sjme_bitStream)(x))
  90
  91 /**
  92  * Input bit stream source.
  93  *
  94  * @since 2024/08/26
  95  */
  96 typedef struct sjme_bitStream_inputBase sjme_bitStream_inputBase;
  97
  98 /**
  99  * Input bit stream source.
 100  *
 101  * @since 2024/08/26
 102  */
 103 typedef struct sjme_bitStream_inputBase* sjme_bitStream_input;
 104
 105 /**
 106  * Output bit stream destination.
 107  *
 108  * @since 2024/08/26
 109  */
 110 typedef struct sjme_bitStream_outputBase sjme_bitStream_outputBase;
 111
 112 /**
 113  * Output bit stream destination.
 114  *
 115  * @since 2024/08/26
 116  */
 117 typedef struct sjme_bitStream_outputBase* sjme_bitStream_output;
 118
 119 /**
 120  * Reads a single byte from the input.
 121  *
 122  * @param inStream The bit stream.
 123  * @param functionData The optional data passed to this function.
 124  * @param readCount The resultant read count, negative value means EOF.
 125  * @param outBuf The buffer of read bytes.
 126  * @param length The number of bytes to read.
 127  * @return On any resultant error, if any.
 128  * @since 2024/08/26
 129  */
 130 typedef sjme_errorCode (*sjme_bitStream_inputReadByteFunc)(
 131         sjme_attrInNotNull sjme_bitStream_input inStream,
 132         sjme_attrInNullable sjme_pointer functionData,
 133         sjme_attrOutNotNull sjme_jint* readCount,
 134         sjme_attrOutNotNullBuf(length) sjme_pointer outBuf,
 135         sjme_attrInPositiveNonZero sjme_jint length);
 136
 137 /**
 138  * Writes a single byte to the output.
 139  *
 140  * @param outStream The bit stream.
 141  * @param functionData The optional data passed to this function.
 142  * @param writeBuf The bytes to write.
 143  * @param length The number of bytes to write.
 144  * @return On any resultant error, if any.
 145  * @since 2024/08/26
 146  */
 147 typedef sjme_errorCode (*sjme_bitStream_outputWriteByteFunc)(
 148         sjme_attrInNotNull sjme_bitStream_output outStream,
 149         sjme_attrInNullable sjme_pointer functionData,
 150         sjme_attrInNotNullBuf(length) sjme_buffer writeBuf,
 151         sjme_attrInPositiveNonZero sjme_jint length);
 152
 153 struct sjme_bitStream_inputBase
 154 {
 155         /** Base bit stream data. */
 156         sjme_bitStream_base base;
 157
 158         /** The read function. */
 159         sjme_bitStream_inputReadByteFunc readFunc;
 160
 161         /** Was EOF hit? */
 162         sjme_jboolean eofHit;
 163 };
 164
 165 struct sjme_bitStream_outputBase
 166 {
 167         /** Base bit stream data. */
 168         sjme_bitStream_base base;
 169
 170         /** The write function. */
 171         sjme_bitStream_outputWriteByteFunc writeFunc;
 172 };
 173
 174 /**
 175  * Returns the number of bits that are ready.
 176  *
 177  * @param ofStream The stream to get the ready count for.
 178  * @param readyBits The number of ready bits.
 179  * @return Any resultant error, if any.
 180  * @since 2024/08/31
 181  */
 182 sjme_errorCode sjme_bitStream_bitsReady(
 183         sjme_attrInNotNull sjme_bitStream ofStream,
 184         sjme_attrOutNotNull sjme_jint* readyBits);
 185
 186 /**
 187  * Skips the given number of bits until the input bit stream is aligned with
 188  * the given alignment, that is the modulo of it is zero.
 189  *
 190  * @param inStream The input bit stream.
 191  * @param alignBit The bit to align to.
 192  * @param outSkipped The number of bits that were skipped, optional.
 193  * @return On any resultant error, if any.
 194  * @since 2024/08/31
 195  */
 196 sjme_errorCode sjme_bitStream_inputAlign(
 197         sjme_attrInNotNull sjme_bitStream_input inStream,
 198         sjme_attrInRange(2, 32) sjme_jint alignBit,
 199         sjme_attrOutNullable sjme_jint* outSkipped);
 200
 201 /**
 202  * Opens an input bit stream.
 203  *
 204  * @param allocPool The pool to allocate within.
 205  * @param resultStream The resultant stream.
 206  * @param readFunc The read function to use.
 207  * @param readFuncData The optional data to pass to the function.
 208  * @param forwardClose The closeable to close, if closed.
 209  * @return On any resultant error, if any.
 210  * @since 2024/08/26
 211  */
 212 sjme_errorCode sjme_bitStream_inputOpen(
 213         sjme_attrInNotNull sjme_alloc_pool allocPool,
 214         sjme_attrOutNotNull sjme_bitStream_input* resultStream,
 215         sjme_attrInNotNull sjme_bitStream_inputReadByteFunc readFunc,
 216         sjme_attrInNullable sjme_pointer readFuncData,
 217         sjme_attrInNullable sjme_closeable forwardClose);
 218
 219 /**
 220  * Opens a bit stream from a memory location.
 221  *
 222  * @param allocPool The pool to allocate within.
 223  * @param resultStream The resultant stream.
 224  * @param base The base memory address.
 225  * @param length The length of the memory block.
 226  * @return Any resultant error, if any.
 227  * @since 2024/08/27
 228  */
 229 sjme_errorCode sjme_bitStream_inputOpenMemory(
 230         sjme_attrInNotNull sjme_alloc_pool allocPool,
 231         sjme_attrOutNotNull sjme_bitStream_input* resultStream,
 232         sjme_attrInNotNull sjme_cpointer base,
 233         sjme_attrInPositive sjme_jint length);
 234
 235 /**
 236  * Opens a bit stream which reads from the given @c sjme_stream_input .
 237  *
 238  * @param allocPool The pool to allocate within.
 239  * @param resultStream The resultant stream.
 240  * @param inputStream The stream to read byte data from.
 241  * @param forwardClose Should close be forwarded to the given stream?
 242  * @return On any resultant error, if any.
 243  * @since 2024/08/26
 244  */
 245 sjme_errorCode sjme_bitStream_inputOpenStream(
 246         sjme_attrInNotNull sjme_alloc_pool allocPool,
 247         sjme_attrOutNotNull sjme_bitStream_input* resultStream,
 248         sjme_attrInNotNull sjme_stream_input inputStream,
 249         sjme_attrInValue sjme_jboolean forwardClose);
 250
 251 /**
 252  * Reads bits from the input source.
 253  *
 254  * @param inStream The stream to read bits from.
 255  * @param bitOrder The order of the bit read.
 256  * @param outValue The resultant value.
 257  * @param bitCount The number of bits to read.
 258  * @return Any resultant error, if any.
 259  * @since 2024/08/27
 260  */
 261 sjme_errorCode sjme_bitStream_inputRead(
 262         sjme_attrInNotNull sjme_bitStream_input inStream,
 263         sjme_attrInValue sjme_bitStream_order bitOrder,
 264         sjme_attrOutNotNull sjme_juint* outValue,
 265         sjme_attrInPositiveNonZero sjme_jint bitCount);
 266
 267 /**
 268  * Opens an output bit stream.
 269  *
 270  * @param allocPool The pool to allocate within.
 271  * @param resultStream The resultant stream.
 272  * @param writeFunc The write function to use.
 273  * @param writeFuncData The optional data to pass to the function.
 274  * @param forwardClose The closeable to close, if closed.
 275  * @return On any resultant error, if any.
 276  * @since 2024/08/26
 277  */
 278 sjme_errorCode sjme_bitStream_outputOpen(
 279         sjme_attrInNotNull sjme_alloc_pool allocPool,
 280         sjme_attrOutNotNull sjme_bitStream_output* resultStream,
 281         sjme_attrInNotNull sjme_bitStream_outputWriteByteFunc writeFunc,
 282         sjme_attrInNullable sjme_pointer writeFuncData,
 283         sjme_attrInNullable sjme_closeable forwardClose);
 284
 285 /**
 286  * Opens an output bit stream which writes to the given output stream.
 287  *
 288  * @param allocPool The pool to allocate within.
 289  * @param resultStream The resultant output bit stream.
 290  * @param outputStream The stream to write.
 291  * @param forwardClose If this is closed, should @c outputStream be closed?
 292  * @return Any resultant error, if any.
 293  * @since 2024/08/28
 294  */
 295 sjme_errorCode sjme_bitStream_outputOpenStream(
 296         sjme_attrInNotNull sjme_alloc_pool allocPool,
 297         sjme_attrOutNotNull sjme_bitStream_output* resultStream,
 298         sjme_attrInNotNull sjme_stream_output outputStream,
 299         sjme_attrInValue sjme_jboolean forwardClose);
 300
 301 /**
 302  * Writes bits to the output destination.
 303  *
 304  * @param outStream The stream to write bits to.
 305  * @param bitOrder The order of the bit write.
 306  * @param inValue The value to write.
 307  * @param bitCount The number of bits to write.
 308  * @return Any resultant error, if any.
 309  * @since 2024/08/27
 310  */
 311 sjme_errorCode sjme_bitStream_outputWrite(
 312         sjme_attrInNotNull sjme_bitStream_output outStream,
 313         sjme_attrInValue sjme_bitStream_order bitOrder,
 314         sjme_attrInValue sjme_juint outValue,
 315         sjme_attrInPositiveNonZero sjme_jint bitCount);
 316
 317 /*--------------------------------------------------------------------------*/
 318
 319 /* Anti-C++. */
 320 #ifdef __cplusplus
 321         #ifdef SJME_CXX_SQUIRRELJME_BITSTREAM_H
 322 }
 323                 #undef SJME_CXX_SQUIRRELJME_BITSTREAM_H
 324                 #undef SJME_CXX_IS_EXTERNED
 325         #endif /* #ifdef SJME_CXX_SQUIRRELJME_BITSTREAM_H */
 326 #endif /* #ifdef __cplusplus */
 327
 328 #endif /* SQUIRRELJME_BITSTREAM_H */