API documentation? about basis_universal

[richgel999]

Agreed - better docs and examples are coming. Also we will be wrapping up the encoder into a single C-style API to make it easier to use programmatically.

[richgel999]

Yes. Right now the priority is standardization. We're currently documenting the ETC1S bitstream format and the .basis format. More documentation and a lib is coming, but we need these other documents first.

To quickly answer your question: For compression, see the file basisu_comp.h. You fill in the basis_compressor_params (which directly correspond to the command line tool's parameters). Then you use basis_compressor to do the actual compression. get_output_basis_file() returns the compressed file data. This is what the command line tool does.

For transcoding, the only .cpp file you need and care about is transcoder/basisu_transcoder.cpp. Class basisu_transcoder does the actual decompression. Studying the WebAssembly wrapper in the WebGL directory should be useful.

[richgel999]

Yes, that's correct. transcode_image_level() returns a status code - if it returns false something went wrong.

Also, if you set BASISU_FORCE_DEVEL_MESSAGES to 1 when compiling the transcoder, that'll enable numerous (hundreds) of transcoder error and warning messages. They will be printed to stdout in in basisu::debug_printf(). This can help you debug transcoder issues.

[GavinNL]

Is this still in the works? I'm trying to do the same thing, but it seems I have to shift through the source code and extract the relevant bits into my own library.

[GavinNL]

Thank you for the info @richgel999 ,

After playing around with the source code I managed to create what looks like some kind of working code. Does this look correct? I tried copying the output data to a vulkan renderer I had using the VK_FORMAT_BC3_UNORM_BLOCK for the image, but I am getting a black texture. Not sure if I'm doing it correctly on the vulkan side, I just wanted to check that my conversion from raw RGBA to BC3 is correct.

I modified the basisu_transcoder.cpp file to remove the javascript stuff.

    basisu::basisu_encoder_init();
    basisu::job_pool jobPool(1);

    basisu::image Bimg;

    // Bimg(i, j) = ... fill pixels 


    basisu::basis_compressor_params params;
    params.m_source_images.push_back( Bimg );
    params.m_read_source_images = false;
    params.m_debug              = true;
    params.m_uastc              = true;
    params.m_mip_gen            = false;
    params.m_pJob_pool          = &jobPool;

    basisu::basis_compressor comp;

    assert( comp.init(params) );

    // compress into Basis format
    auto err = comp.process();

    assert( err == basisu::basis_compressor::cECSuccess);

    auto compressedByteSize = comp.get_basis_file_size();   

    basis_file B( comp.get_output_basis_file() );

    // transcode to BC3 compressed format
    auto status =
    B.transcodeImage( /* const emscripten::val& dst ,  - removed from my implementation*/
                            0,
                            0,
                            basist::transcoder_texture_format::cTFBC3,
                            0,
                             1);

    assert( status == 0 );

    // FINAL COMPRESSED BC3 image data for a single Image with 1 mipmap level
    assert( B.m_dst.size() > 0 );
   // copy B.m_dst.data() to GPU image using VK_FORMAT_BC3_UNORM_BLOCK format

[richgel999]

Are you calling basisu_encoder_init(); before doing anything else?

Also, before using the transcoder, be sure to call basist::basisu_transcoder_init() (basisu_encoder_init() does this for you).

[richgel999]

Also, looks like you are using the wrappers for WebGL, so be sure to call basis_init() first.

[richgel999]

Overall what you're doing should work. I will be adding an example that basically does what you're doing (except calls the transcoder directly) after we release the ETC1S documentation. Please bear with us!

[GavinNL]

Hmm. I was calling basisu_encoder_init() but I wasn't calling basist::basisu_transcoder_init(), I added that in but I'm still getting a black texture. It's possible I'm doing something wrong on the Vulkan side, so I'll look into this a bit more.

Thanks for the info, I have something to get me started at least!

[GavinNL]

@richgel999 , I think I figured it out. you have to call m_transcoder.begin_transcoder( data, size) before you can call basisFile.transcodeImage( ... )

[lihongyi1234]

@richgel999 @GavinNL hello ,i run program above correct ,the .basis is about 1M,i want to use ETCIS (low/medium quality format), i change params.m_uastc = false, but it run failed, log is there ,i want to know if everywhere wrong with my program, or something has omitted.
(Slice: 0, alpha: 0, orig width/height: 1024x1024, width/height: 1024x1024, first_block: 0, x: 0, mip_level: 0, iframe: 0
ERROR: basisu_frontend::init() failed!)

    basisu::basisu_encoder_init();

basisu::basis_compressor_params params;
//params.m_source_images.push_back(Bimg);
params.m_source_filenames.emplace_back(in_fn);
params.m_out_filename = out_fn;
params.m_read_source_images = true;

params.m_write_output_basis_files = true;
params.m_debug = true;
params.m_uastc = false;
params.m_mip_gen = false;

basisu::basis_compressor comp;

if (!comp.init(params))
{
	printf("init failed\n");
}
	
// compress into Basis format
auto err = comp.process();

[sutongkui]

I'm integrating it to UE4.18, If I just want to save it in an uint8 buffer(avoid write .basis file to disk), and then decode the buffer, just save basisu_backend_output.m_slice_image_data? For example, I want to implement the below interface:
bool EncodeBuffer(const FBasisEncodeParameters& Parameters, TArray<uint8>& OutBuffer);
There are 2 ways in my mind,
1, Fill the image in memory, call process but disable write file to disk. Which means I need to hack the code, the disadvatage is it will not be convient to sync with this repo in the future.
2. Make a temp png file to disk and then call basisu.exe to finish the compression, then load the .astc file and fill it to a buffer(maybe need to remove the header). It means multiple I/O operations cause there are many png.

Looking for your advice.

[richgel999]

Call basis_compressor::get_output_basis_file() to get the output file, and set m_write_output_basis_files to false. This is what we do in JavaScript. You can check out the JS wrappers over the compressor API, which should assist you: webgl/transcoder/basis_wrappers.cpp.

See class basis_encoder. It's really simple.