Cosm API - Data Compression Functions

[Cosm Logo]

Data Compression Functions

v3CompressInit
v3Compress
v3CompressEnd

v3CompressInit

Syntax

#include "compress.h"
s32 v3CompressInit( v3_BUFFER * output, v3_ENCODER_TMP * tmp,
  u32 compression_type, u32 direction, u32 level );

Description

Initializes the output buffer and sets up the temporary data structure tmp needed to perform the type of compression requested. direction must be either V3_ENCODER_ENCODE (compress) or V3_ENCODER_DECODE (decompress). level is a number ranging from 1 to 9 representing the amount of compression to attempt, 1 being fast, 9 being intensive. Those who need to add additional compression types should see Encoder Functions as the compression functions are actually an interface to the encoder functions.

Do not call v3BufferCreate on output yourself - you still need to v3BufferFree it after you're done with it of course.

Predefined compression types:

V3_COMPRESS_BZIP2: bzip2 compression.
V3_COMPRESS_BASE64: Base64 encoding - expands the data 33%.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_ENCODER_ERROR_PARAM: Invalid parameter.
V3_ENCODER_ERROR_STATE: Invalid state or functions called in the wrong order.
V3_ENCODER_ERROR_MEMORY: Out of memory problem.
V3_ENCODER_ERROR_FATAL: Fatal algorithm error, call ...End().
V3_ENCODER_ERROR_MODE: Invalid mode or params sent to algorithm.

Example

  v3_BUFFER buf;
  v3_ENCODER_TMP tmp;

  v3MemSet( &buf, v3u64u32( sizeof( v3_BUFFER ) ), 0 );
  v3MemSet( &tmp, v3u64u32( sizeof( v3_ENCODER_TMP ) ), 0 );

  if ( v3CompressInit( &buf, &tmp, V3_COMPRESS_BZIP2,
    V3_ENCODER_ENCODE, 9 ) != V3_PASS )
  {
    return( -1 );
  }

v3Compress

Syntax

#include "compress.h"
s32 v3Compress( v3_BUFFER * output, v3_ENCODER_TMP * tmp,
  const void * const data, u64 length );

Description

Feed length bytes of data into the compression routines. Any compressed data will be placed into the output buffer but may not be put into the output buffer after every call for some algorithms.

Make sure your data has been v3Save'd before using this.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_ENCODER_ERROR_PARAM: Invalid parameter.
V3_ENCODER_ERROR_STATE: Invalid state or functions called in the wrong order.
V3_ENCODER_ERROR_MEMORY: Out of memory problem.
V3_ENCODER_ERROR_FATAL: Fatal algorithm error, call ...End().

Example

  v3_BUFFER buf;
  v3_ENCODER_TMP tmp;
  u8 data[8] = { 0, 1, 2, 3, 3, 3, 3, 4 };
  u32 i;

  /* ... */
  
  for ( i = 0 ; i < 100 ; i++ )
  {
    if ( v3Compress( &buf, &tmp, data, v3u64u32( 8 ) ) != V3_PASS )
    {
      return( -2 );
    }
  }

v3CompressEnd

Syntax

#include "compress.h"
s32 v3CompressEnd( v3_BUFFER * output, v3_ENCODER_TMP * tmp );

Description

Clear any temporary data and put the last of the compressed data into the buffer. Make sure to empty and v3BufferFree the output buffer of your data after calling this function.

If this function fails, you must call it again. This second call will always succeed and clean up any mess.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_ENCODER_ERROR_PARAM: Invalid parameter.
V3_ENCODER_ERROR_STATE: Invalid state or functions called in the wrong order.
V3_ENCODER_ERROR_FATAL: Fatal algorithm error, call ...End().

Example

  v3_BUFFER buf;
  v3_ENCODER_TMP tmp;

  /* ... */
  
  if ( v3CompressEnd( &buf, &tmp ) != V3_PASS )
  {
    /* v3CompressEnd() must be called again on an error */
    v3CompressEnd( &tmp );

    return( -3 );
  }

  /* empty out the buffer */

  /* then dont forget to free it */
  v3BufferFree( &buf );