Cosm API - Encoder Functions

[Cosm Logo]

Encoder Functions

v3EncoderInit
v3Encoder
v3EncoderEnd

v3EncoderInit

Syntax

#include "encoder.h"
s32 v3EncoderInit( v3_BUFFER * output, v3_ENCODER_TMP * tmp,
  s32 (*EInit)( v3_ENCODER_TMP *, u32, const void * const ),
  s32 (*E)( v3_BUFFER *, v3_ENCODER_TMP *, const void * const, u64 ),
  s32 (*EEnd)( v3_BUFFER *, v3_ENCODER_TMP * ),
  s32 (*DInit)( v3_ENCODER_TMP *, u32, const void * const ),
  s32 (*D)( v3_BUFFER *, v3_ENCODER_TMP *, const void * const, u64 ),
  s32 (*DEnd)( v3_BUFFER *, v3_ENCODER_TMP * ),
  u32 direction, u32 mode, const void * const params );

Description

Initializes the output buffer and sets up the temporary data structure tmp needed to perform the type of encoding requested. direction must be either V3_ENCODER_ENCODE or V3_ENCODER_DECODE. mode and params are algorithm dependant parameters. EInit, E, EEnd, DInit, D, and DEnd are callback functions to implement the low level specifics of the encoding algorithm. Each should return V3_PASS or a V3_ENCODER_ERROR_* error. See the Cosm compression or security code for examples of how to use this API to add support for an encoding algorithm.

Since this is a rather painful API for users, you should always define a macro for the 6 callback functions.

Note: Do not call v3BufferCreate on output yourself - you still need to zero it (v3MemAlloc or v3MemSet) before and v3BufferFree it after you're done with it of course.

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

  #include "compress.h" /* to import the V3_COMPRESS_* macros */

  v3_BUFFER buf;
  v3_ENCODER_TMP tmp;

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

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

v3Encoder

Syntax

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

Description

Feed length bytes of data into the encoding routines. Any encoded 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 ( v3Encoder( &buf, &tmp, data, v3u64u32( 8 ) ) != V3_PASS )
    {
      return( -2 );
    }
  }

v3EncoderEnd

Syntax

#include "encoder.h"
s32 v3EncoderEnd( v3_BUFFER * output, v3_ENCODER_TMP * tmp );

Description

Clear any temporary data and put the last of the encoded 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 ( v3EncoderEnd( &buf, &tmp ) != V3_PASS )
  {
    /* v3EncoderEnd() must be called again on an error */
    v3EncoderEnd( &tmp );

    return( -3 );
  }

  /* empty out the buffer */

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