Thanks for deciding to contribute to meshoptimizer! These guidelines will try to help make the process painless and efficient.
## Questions
If you have a question regarding the library usage, please [open a GitHub issue](https://github.com/zeux/meshoptimizer/issues/new).
Some questions just need answers, but it's nice to keep them for future reference in case other people want to know the same thing.
Some questions help improve the library interface or documentation by inspiring future changes.
## Bugs
If the library doesn't compile on your system, compiles with warnings, doesn't seem to run correctly for your input data or if anything else is amiss, please [open a GitHub issue](https://github.com/zeux/meshoptimizer/issues/new).
It helps if you note the version of the library this issue happens in, the version of your compiler for compilation issues, and a reproduction case for runtime bugs.
Of course, feel free to [create a pull request](https://help.github.com/articles/about-pull-requests/) to fix the bug yourself.
## Features
New algorithms and improvements to existing algorithms are always welcome; you can open an issue or make the change yourself and submit a pull request.
For major features, consider opening an issue describing an improvement you'd like to see or make before opening a pull request.
This will give us a chance to discuss the idea before implementing it - some algorithms may not be easy to integrate into existing programs, may not be robust to arbitrary meshes or may be expensive to run or implement/maintain, so a discussion helps make sure these don't block the algorithm development.
## Code style
Contributions to this project are expected to follow the existing code style.
`.clang-format` file mostly defines syntactic styling rules (you can run `make format` to format the code accordingly).
As for naming conventions, this library uses `snake_case` for variables, `lowerCamelCase` for functions, `UpperCamelCase` for types, `kCamelCase` for global constants and `SCARY_CASE` for macros. All public functions/types must additionally have an extra `meshopt_` prefix to avoid symbol conflicts.
## Dependencies
Please note that this library uses C89 interface for all APIs and a C++98 implementation - C++11 features can not be used.
This choice is made to maximize compatibility to make sure that any toolchain, including legacy proprietary gaming console toolchains, can compile this code.
Additionally, the library code has zero external dependencies, does not depend on STL and does not use RTTI or exceptions.
This, again, maximizes compatibility and makes sure the library can be used in environments where STL use is discouraged or prohibited, as well as maximizing runtime performance and minimizing compilation times.
The demo program uses STL since it serves as an example of usage and as a test harness, not as production-ready code.
## Testing
All pull requests will run through a continuous integration pipeline using GitHub Actions that will run the built-in unit tests and integration tests on Windows, macOS and Linux with gcc, clang and msvc compilers.
You can run the tests yourself using `make test` or building the demo program with `cmake -DBUILD_DEMO=ON` and running it.
Unit tests can be found in `demo/tests.cpp` and functional tests - in `demo/main.cpp`; when making code changes please try to make sure they are covered by an existing test or add a new test accordingly.
## Documentation
Documentation for this library resides in the `meshoptimizer.h` header, with examples as part of a usage manual available in `README.md`.
Changes to documentation are always welcome and should use issues/pull requests as outlined above; please note that `README.md` only contains documentation for stable algorithms, as experimental algorithms may change the interface without concern for backwards compatibility.
## Sensitive communication
If you prefer to not disclose the issues or information relevant to the issue such as reproduction case to the public, you can always contact the author via e-mail (arseny.kapoulkine@gmail.com).
// Copyright (C) 2019-2020 Binomial LLC. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
#pragma once
namespacebasisu
{
// Always little endian 2-4 byte unsigned int
template<uint32_tNumBytes>
structpacked_uint
{
uint8_tm_bytes[NumBytes];
operatoruint32_t()const
{
uint32_tresult=0;
for(uint32_ti=0;i<NumBytes;i++)
result|=m_bytes[i]<<(8*i);
returnresult;
}
};
}
namespacebasist
{
// Slice desc header flags
enumbasis_slice_desc_flags
{
cSliceDescFlagsHasAlpha=1,
cSliceDescFlagsFrameIsIFrame=2// Video only: Frame doesn't refer to previous frame (no usage of conditional replenishment pred symbols)
};
#pragma pack(push)
#pragma pack(1)
structbasis_slice_desc
{
basisu::packed_uint<3>m_image_index;// The index of the source image provided to the encoder (will always appear in order from first to last, first image index is 0, no skipping allowed)
basisu::packed_uint<1>m_level_index;// The mipmap level index (mipmaps will always appear from largest to smallest)
basisu::packed_uint<2>m_orig_width;// The original image width (may not be a multiple of 4 pixels)
basisu::packed_uint<2>m_orig_height;// The original image height (may not be a multiple of 4 pixels)
basisu::packed_uint<2>m_num_blocks_x;// The slice's block X dimensions. Each block is 4x4 pixels. The slice's pixel resolution may or may not be a power of 2.
basisu::packed_uint<2>m_num_blocks_y;// The slice's block Y dimensions.
basisu::packed_uint<4>m_file_ofs;// Offset from the header to the start of the slice's data
basisu::packed_uint<4>m_file_size;// The size of the compressed slice data in bytes
basisu::packed_uint<2>m_slice_data_crc16;// The CRC16 of the compressed slice data, for extra-paranoid use cases
};
// File header files
enumbasis_header_flags
{
cBASISHeaderFlagETC1S=1,// Always set for ETC1S files. Not set for UASTC files.
cBASISHeaderFlagYFlipped=2,// Set if the texture had to be Y flipped before encoding
cBASISHeaderFlagHasAlphaSlices=4// True if any slices contain alpha (for ETC1S, if the odd slices contain alpha data)
};
// The image type field attempts to describe how to interpret the image data in a Basis file.
// The encoder library doesn't really do anything special or different with these texture types, this is mostly here for the benefit of the user.
// We do make sure the various constraints are followed (2DArray/cubemap/videoframes/volume implies that each image has the same resolution and # of mipmap levels, etc., cubemap implies that the # of image slices is a multiple of 6)
enumbasis_texture_type
{
cBASISTexType2D=0,// An arbitrary array of 2D RGB or RGBA images with optional mipmaps, array size = # images, each image may have a different resolution and # of mipmap levels
cBASISTexType2DArray=1,// An array of 2D RGB or RGBA images with optional mipmaps, array size = # images, each image has the same resolution and mipmap levels
cBASISTexTypeCubemapArray=2,// an array of cubemap levels, total # of images must be divisable by 6, in X+, X-, Y+, Y-, Z+, Z- order, with optional mipmaps
cBASISTexTypeVideoFrames=3,// An array of 2D video frames, with optional mipmaps, # frames = # images, each image has the same resolution and # of mipmap levels
cBASISTexTypeVolume=4,// A 3D texture with optional mipmaps, Z dimension = # images, each image has the same resolution and # of mipmap levels