Compressonator SDK¶
Compressonator SDK’s supported codecs includes BC1-BC7/DXTC, ETC1, ETC2, ASTC, ATC, ATI1N, ATI2N.
Error Codes¶
All Compressonator API calls return a int success 0 (CMP_OK) or error value > 0 (CMP_ERR) for a more detailed and up to date list look at the file Compressonator.h enum CMP_ERROR values.
CMP_OK = 0, // Ok.
CMP_ABORTED, // The conversion was aborted.
CMP_ERR_INVALID_SOURCE_TEXTURE, // The source texture is invalid.
CMP_ERR_INVALID_DEST_TEXTURE, // The destination texture is invalid.
CMP_ERR_UNSUPPORTED_SOURCE_FORMAT, // The source format is not a supported format.
CMP_ERR_UNSUPPORTED_DEST_FORMAT, // The destination format is not a supported format.
CMP_ERR_UNSUPPORTED_GPU_ASTC_DECODE, // The gpu hardware is not supported.
CMP_ERR_UNSUPPORTED_GPU_BASIS_DECODE, // The gpu hardware is not supported.
CMP_ERR_SIZE_MISMATCH, // The source and destination texture sizes do not match.
CMP_ERR_UNABLE_TO_INIT_CODEC, // Compressonator was unable to initialize the codec needed for conversion.
CMP_ERR_UNABLE_TO_INIT_DECOMPRESSLIB, // GPU_Decode Lib was unable to initialize the codec needed for decompression .
CMP_ERR_UNABLE_TO_INIT_COMPUTELIB, // Compute Lib was unable to initialize the codec needed for compression.
CMP_ERR_CMP_DESTINATION, // Error in compressing destination texture
CMP_ERR_MEM_ALLOC_FOR_MIPSET, // Memory Error: allocating MIPSet compression level data buffer
CMP_ERR_UNKNOWN_DESTINATION_FORMAT, // The destination Codec Type is unknown! In SDK refer to GetCodecType()
CMP_ERR_FAILED_HOST_SETUP, // Failed to setup Host for processing
CMP_ERR_PLUGIN_FILE_NOT_FOUND, // The required plugin library was not found
CMP_ERR_UNABLE_TO_LOAD_FILE, // The requested file was not loaded
CMP_ERR_UNABLE_TO_CREATE_ENCODER, // Request to create an encoder failed
CMP_ERR_UNABLE_TO_LOAD_ENCODER, // Unable to load an encode library
CMP_ERR_NOSHADER_CODE_DEFINED, // No shader code is available for the requested framework
CMP_ERR_GPU_DOESNOT_SUPPORT_COMPUTE, // The GPU device selected does not support compute
CMP_ERR_GENERIC // An unknown error occurred.
Convert Texture¶
The main API call for both compression and decompression as well as texture conversion:
/// Converts the source texture to the destination texture
/// This can be compression, decompression or converting between two uncompressed formats.
/// \param[in] pSourceTexture A pointer to the source texture.
/// \param[in] pDestTexture A pointer to the destination texture.
/// \param[in] pOptions A pointer to the compression options - can be NULL.
/// \param[in] pFeedbackProc A pointer to the feedback function - can be NULL.
/// \param[in] pUser1 User data to pass to the feedback function.
/// \param[in] pUser2 User data to pass to the feedback function.
/// \return CMP_OK if successful, otherwise the error code.
CMP_ERROR CMP_API CMP_ConvertTexture(CMP_Texture* pSourceTexture, CMP_Texture* pDestTexture, const CMP_CompressOptions* pOptions,
CMP_Feedback_Proc pFeedbackProc, CMP_DWORD_PTR pUser1, CMP_DWORD_PTR pUser2);
Example Usage of Compressonator API¶
You will need to include a header file and a lib file: Compressonator.h and Compressonator_MD.lib
and a simple usage is shown as below:
//==========================
// Load Source Texture
//==========================
CMP_Texture srcTexture;
// note that LoadDDSFile function is a utils function to initialize the source CMP_Texture
// you can also initialize the source CMP_Texture the same way as initialize destination CMP_Texture
if (!LoadDDSFile(pszSourceFile, srcTexture))
{
std::printf("Error loading source file!\n");
return 0;
}
//===================================
// Initialize Compressed Destination
//===================================
CMP_Texture destTexture;
destTexture.dwSize = sizeof(destTexture);
destTexture.dwWidth = srcTexture.dwWidth;
destTexture.dwHeight = srcTexture.dwHeight;
destTexture.dwPitch = 0;
destTexture.format = destFormat;
destTexture.dwDataSize = CMP_CalculateBufferSize(&destTexture);
destTexture.pData = (CMP_BYTE*)malloc(destTexture.dwDataSize);
//==========================
// Set Compression Options
//==========================
CMP_CompressOptions options = {0};
options.dwSize = sizeof(options);
options.fquality = fQuality;
options.dwnumThreads = 8;
//==========================
// Compress Texture
//==========================
CMP_ERROR cmp_status;
cmp_status = CMP_ConvertTexture(&srcTexture, &destTexture, &options, &CompressionCallback, NULL, NULL);
if (cmp_status != CMP_OK)
{
free(srcTexture.pData);
free(destTexture.pData);
std::printf("Compression returned an error %d\n", cmp_status);
return cmp_status;
}
//==========================
// Save Compressed Testure
//==========================
if (cmp_status == CMP_OK)
SaveDDSFile(pszDestFile, destTexture);
free(srcTexture.pData);
free(destTexture.pData);
Example projects have been provided here with:
- sdk_example1 demonstrates simple SDK API usage as shown above.
- sdk_example2 demonstrates how to use the SDK API in multihreaded environment.
- sdk_exmaple3 demonstrates how to use the block level SDK API.
These examples are also distributed through Compressonator SDK installer in the release page.