diff options
Diffstat (limited to 'libpsn00b/include/psxpress.h')
| -rw-r--r-- | libpsn00b/include/psxpress.h | 158 |
1 files changed, 124 insertions, 34 deletions
diff --git a/libpsn00b/include/psxpress.h b/libpsn00b/include/psxpress.h index 2106a53..dc1d52c 100644 --- a/libpsn00b/include/psxpress.h +++ b/libpsn00b/include/psxpress.h @@ -3,6 +3,23 @@ * (C) 2022 spicyjpeg - MPL licensed */ +/** + * @file psxpress.h + * @brief MDEC library header + * + * @details This is a fully original reimplementation of the official SDK's + * "data compression" library. This library is made up of two parts, the MDEC + * API and functions to decompress Huffman-encoded bitstreams (.BS files, or + * frames in .STR files) into data to be fed to the MDEC. Two different + * implementations of the latter are provided, one using the GTE and scratchpad + * region and an older one using a large lookup table in main RAM. + * + * FMV playback is not part of this library per se, but can implemented using + * the APIs defined here alongside some code to stream data from the CD drive. + * + * Currently only version 1 and 2 .BS files are supported. + */ + #ifndef __PSXPRESS_H #define __PSXPRESS_H @@ -70,7 +87,9 @@ extern "C" { #endif /** - * @brief Resets the MDEC and aborts any MDEC DMA transfers. If mode = 0, the + * @brief Resets and optionally initializes the MDEC. + * + * @details Resets the MDEC and aborts any MDEC DMA transfers. If mode = 0, the * default IDCT matrix and quantization tables are also loaded and the MDEC is * put into color output mode, discarding any custom environment previously set * with DecDCTPutEnv(). @@ -78,15 +97,19 @@ extern "C" { * DecDCTReset(0) must be called at least once prior to using the MDEC. * * @param mode + * + * @see DecDCTPutEnv() */ void DecDCTReset(int mode); /** - * @brief Uploads the specified decoding environment's quantization tables and - * IDCT matrix to the MDEC, or restores the default tables if a null pointer is - * passed. Calling this function is normally not required as DecDCTReset(0) - * initializes the MDEC with the default tables, but it may be useful for e.g. - * decoding JPEG or a format with custom quantization tables. + * @brief Loads default or custom quantization and IDCT tables into the MDEC. + * + * @details Uploads the specified decoding environment's quantization tables + * and IDCT matrix to the MDEC, or restores the default tables if a null + * pointer is passed. Calling this function is normally not required as + * DecDCTReset(0) initializes the MDEC with the default tables, but it may be + * useful for e.g. decoding JPEG or a format with custom quantization tables. * * The second argument, not present in the official SDK, specifies whether the * MDEC shall be put into color (0) or monochrome (1) output mode. In @@ -103,12 +126,16 @@ void DecDCTReset(int mode); void DecDCTPutEnv(const DECDCTENV *env, int mono); /** - * @brief Sets up the MDEC to start fetching and decoding the given buffer. - * This function is meant to be used with buffers generated by DecDCTvlc(): the - * first 32-bit word of the buffer is initially copied to the MDEC0 register, - * then all subsequent data is read in 128-byte (32-word) chunks. The length of - * the stream (in 32-bit units, minus the first word) is encoded by DecDCTvlc() - * in the lower 16 bits of the first word. + * @brief Feeds the MDEC with a run-length code buffer from the specified + * location. + * + * @details Sets up the MDEC to start fetching and decoding the given buffer. + * This function is meant to be used with buffers generated by DecDCTvlc(), + * DecDCTvlc2() or their variants: the first 32-bit word of the buffer is + * initially copied to the MDEC0 register, then all subsequent data is read in + * 128-byte (32-word) chunks. The length of the stream (in 32-bit units, minus + * the first word) is encoded by DecDCTvlc() in the lower 16 bits of the first + * word. * * The mode argument optionally specifies the output color depth (0 for 16bpp, * 1 for 24bpp) if not already set in the first word. Passing -1 will result in @@ -117,11 +144,15 @@ void DecDCTPutEnv(const DECDCTENV *env, int mono); * * @param data * @param mode DECDCT_MODE_* or -1 + * + * @see DecDCTinRaw(), DecDCTinSync() */ void DecDCTin(const uint32_t *data, int mode); /** - * @brief Configures the MDEC to automatically fetch data (the input stream, + * @brief Feeds the MDEC with raw data from the specified location. + * + * @details Configures the MDEC to automatically fetch data (the input stream, * IDCT matrix or quantization tables) in 128-byte (32-word) chunks from the * specified address in main RAM. The transfer is stopped, and any callback * registered with DMACallback(0) is fired, once a certain number of 32-bit @@ -135,13 +166,17 @@ void DecDCTin(const uint32_t *data, int mode); * * @param data * @param length Number of 32-bit words to read (must be multiple of 32) + * + * @see DecDCTin(), DecDCTinSync() */ void DecDCTinRaw(const uint32_t *data, size_t length); /** - * @brief Waits for the MDEC to finish decoding the input stream (if mode = 0) - * or returns whether it is busy (if mode = 1). MDEC commands can be issued - * only when the MDEC isn't busy. + * @brief Waits for an MDEC input transfer to finish or returns its status. + * + * @details Waits for the MDEC to finish decoding the input stream (if + * mode = 0) or returns whether it is busy (if mode = 1). MDEC commands can be + * issued only when the MDEC isn't busy. * * WARNING: DecDCTinSync(0) might time out and return -1 if the MDEC can't * output decoded data, e.g. if the length passed DecDCTout() was too small and @@ -155,7 +190,9 @@ void DecDCTinRaw(const uint32_t *data, size_t length); int DecDCTinSync(int mode); /** - * @brief Configures the MDEC to automatically transfer decoded image data in + * @brief Writes image data decoded by the MDEC to the specified location. + * + * @details Configures the MDEC to automatically transfer decoded image data in * 128-byte (32-word) chunks to the specified address in main RAM. MDEC * operation is paused once a certain number of 32-bit words have been output * and can be resumed by calling DecDCTout() again: the MDEC will continue @@ -168,12 +205,16 @@ int DecDCTinSync(int mode); * * @param data * @param length Number of 32-bit words to output (must be multiple of 32) + * + * @see DecDCToutSync() */ void DecDCTout(uint32_t *data, size_t length); /** - * @brief Waits until the transfer set up by DecDCTout() finishes (if mode = 0) - * or returns whether it is still in progress (if mode = 1). + * @brief Waits for an MDEC output transfer to finish or returns its status. + * + * @details Waits until the transfer set up by DecDCTout() finishes (if + * mode = 0) or returns whether it is still in progress (if mode = 1). * * WARNING: DecDCToutSync(0) might time out and return -1 if the MDEC is unable * to consume enough input data in order to produce the desired amount of data. @@ -186,7 +227,9 @@ void DecDCTout(uint32_t *data, size_t length); int DecDCToutSync(int mode); /** - * @brief Begins decompressing the contents of a .BS file (or of a single .STR + * @brief Decompresses or begins decompressing a .BS file into MDEC codes. + * + * @details Begins decompressing the contents of a .BS file (or of a single STR * frame) into a buffer that can be passed to DecDCTin(). This function uses a * small (<1 KB) lookup table combined with the GTE to accelerate the process; * performance is roughly on par with DecDCTvlcStart2() if the lookup table @@ -212,11 +255,15 @@ int DecDCToutSync(int mode); * @param max_size Maximum number of 32-bit words to output * @param bs * @return 0, 1 if more data needs to be output or -1 in case of failure + * + * @see DecDCTvlcContinue(), DecDCTvlcCopyTable() */ int DecDCTvlcStart(VLC_Context *ctx, uint32_t *buf, size_t max_size, const uint32_t *bs); /** - * @brief Resumes the decompression process started by DecDCTvlcStart(). The + * @brief Resumes or finishes decompressing a .BS file into MDEC codes. + * + * @details Resumes the decompression process started by DecDCTvlcStart(). The * state of the decompressor is contained entirely in the VLC_Context structure * so an arbitrary number of bitstreams can be decoded concurrently (although * the limited CPU power makes it impractical to do so) by keeping a separate @@ -236,14 +283,18 @@ int DecDCTvlcStart(VLC_Context *ctx, uint32_t *buf, size_t max_size, const uint3 * @param buf * @param max_size Maximum number of 32-bit words to output * @return 0, 1 if more data needs to be output or -1 in case of failure + * + * @see DecDCTvlcStart() */ int DecDCTvlcContinue(VLC_Context *ctx, uint32_t *buf, size_t max_size); /** - * A wrapper around DecDCTvlcStart() and DecDCTvlcContinue() for compatibility - * with the official SDK. This function uses an internal context; additionally, - * the maximum output buffer size is not passed as an argument but is instead - * set by calling DecDCTvlcSize(). + * @brief Decompresses a .BS file into MDEC codes. + * + * @details A wrapper around DecDCTvlcStart() and DecDCTvlcContinue() for + * compatibility with the official SDK. This function uses an internal context; + * additionally, the maximum output buffer size is not passed as an argument + * but is instead set by calling DecDCTvlcSize(). * * This function behaves identically to DecDCTvlcContinue() if bs = 0 and * DecDCTvlcStart() otherwise. @@ -257,21 +308,34 @@ int DecDCTvlcContinue(VLC_Context *ctx, uint32_t *buf, size_t max_size); * @param bs Pointer to bitstream data or 0 to resume decoding * @param buf * @return 0, 1 if more data needs to be output or -1 in case of failure + * + * @see DecDCTvlcSize(), DecDCTvlcCopyTable() */ int DecDCTvlc(const uint32_t *bs, uint32_t *buf); /** - * @brief Sets the maximum number of 32-bit words that a single call to + * @brief Sets the maximum amount of data to be decompressed. + * + * @details Sets the maximum number of 32-bit words that a single call to * DecDCTvlc() will output. If size = 0, the entire frame will always be * decoded in one shot. * + * Note that DecDCTvlcStart() and DecDCTvlcContinue() do not use the value set + * by this function and instead expect the maximum size to be passed as an + * argument. + * * @param size Maximum number of 32-bit words to output - * @return Previously set value + * @return Previously set value + * + * @see DecDCTvlc() */ size_t DecDCTvlcSize(size_t size); /** - * @brief Copies the small (<1 KB) lookup table used by DecDCTvlcContinue(), + * @brief Moves the lookup table used by the .BS decompressor to the scratchpad + * region. + * + * @details Copies the small (<1 KB) lookup table used by DecDCTvlcContinue(), * DecDCTvlcStart() and DecDCTvlc() (a DECDCTTAB structure) to the specified * address. A copy of this table is always present in main RAM, however this * function can be used to copy it to the scratchpad region to boost @@ -287,7 +351,10 @@ size_t DecDCTvlcSize(size_t size); void DecDCTvlcCopyTable(DECDCTTAB *addr); /** - * @brief Begins decompressing the contents of a .BS file (or of a single .STR + * @brief Decompresses or begins decompressing a .BS file into MDEC codes + * (alternate implementation). + * + * @details Begins decompressing the contents of a .BS file (or of a single STR * frame) into a buffer that can be passed to DecDCTin(). This function uses a * large (34 KB) lookup table that must be loaded into main RAM beforehand by * calling DecDCTvlcBuild(), but does not use the GTE nor the scratchpad. @@ -311,11 +378,16 @@ void DecDCTvlcCopyTable(DECDCTTAB *addr); * @param max_size Maximum number of 32-bit words to output * @param bs * @return 0, 1 if more data needs to be output or -1 in case of failure + * + * @see DecDCTvlcContinue2(), DecDCTvlcBuild() */ int DecDCTvlcStart2(VLC_Context *ctx, uint32_t *buf, size_t max_size, const uint32_t *bs); /** - * @brief Resumes the decompression process started by DecDCTvlcStart2(). The + * @brief Resumes or finishes decompressing a .BS file into MDEC codes + * (alternate implementation). + * + * @details Resumes the decompression process started by DecDCTvlcStart2(). The * state of the decompressor is contained entirely in the VLC_Context structure * so an arbitrary number of bitstreams can be decoded concurrently (although * the limited CPU power makes it impractical to do so) by keeping a separate @@ -333,11 +405,15 @@ int DecDCTvlcStart2(VLC_Context *ctx, uint32_t *buf, size_t max_size, const uint * @param buf * @param max_size Maximum number of 32-bit words to output * @return 0, 1 if more data needs to be output or -1 in case of failure + * + * @see DecDCTvlcStart2() */ int DecDCTvlcContinue2(VLC_Context *ctx, uint32_t *buf, size_t max_size); /** - * A wrapper around DecDCTvlcStart2() and DecDCTvlcContinue2() for + * @brief Decompresses a .BS file into MDEC codes (alternate implementation). + * + * @details A wrapper around DecDCTvlcStart2() and DecDCTvlcContinue2() for * compatibility with the official SDK. This function uses an internal context; * additionally, the maximum output buffer size is not passed as an argument * but is instead set by calling DecDCTvlcSize2(). @@ -353,21 +429,35 @@ int DecDCTvlcContinue2(VLC_Context *ctx, uint32_t *buf, size_t max_size); * @param buf * @param table Pointer to decompressed table or 0 to use last table used * @return 0, 1 if more data needs to be output or -1 in case of failure + * + * @see DecDCTvlcSize2(), DecDCTvlcBuild() */ int DecDCTvlc2(const uint32_t *bs, uint32_t *buf, DECDCTTAB2 *table); /** - * @brief Sets the maximum number of 32-bit words that a single call to + * @brief Sets the maximum amount of data to be decompressed (alternate + * implementation). + * + * @details Sets the maximum number of 32-bit words that a single call to * DecDCTvlc2() will output. If size = 0, the entire frame will always be * decoded in one shot. * + * Note that DecDCTvlcStart2() and DecDCTvlcContinue2() do not use the value + * set by this function and instead expect the maximum size to be passed as an + * argument. + * * @param size Maximum number of 32-bit words to output - * @return Previously set value + * @return Previously set value + * + * @see DecDCTvlc2() */ size_t DecDCTvlcSize2(size_t size); /** - * @brief Generates the lookup table required by DecDCTvlcStart2(), + * @brief Generates the lookup table used by the alternate implementation of + * the .BS decompressor. + * + * @details Generates the lookup table required by DecDCTvlcStart2(), * DecDCTvlcContinue2() and DecDCTvlc2() (a DECDCTTAB2 structure) into the * specified buffer. Since the table is relatively large (34 KB), it is * recommended to only generate it in a dynamically-allocated buffer when |