Document steps to add a new compression method in ImfCompression.h (A…

…cademySoftwareFoundation#1672) * Document steps in ImfCompression.h Signed-off-by: Philippe Leprince <[email protected]> * Add some steps I had missed. Signed-off-by: Philippe Leprince <[email protected]> * Move description to ImfCompression.cpp and mention the C API first. Signed-off-by: Philippe Leprince <[email protected]> * no functional change: use regular comment style and trim trailing whitespace. Signed-off-by: Philippe Leprince <[email protected]> --------- Signed-off-by: Philippe Leprince <[email protected]>
cary-ilm · Mar 23, 2024 · 272e4b3 · 272e4b3
1 parent 3c9e34a
commit 272e4b3
Show file tree

Hide file tree

Showing 2 changed files with 94 additions and 13 deletions.
diff --git a/src/lib/OpenEXR/ImfCompression.cpp b/src/lib/OpenEXR/ImfCompression.cpp
@@ -2,6 +2,87 @@
 // SPDX-License-Identifier: BSD-3-Clause
 // Copyright (c) Contributors to the OpenEXR Project.
 //
+// -----------------------------------------------------------------------------
+//
+//  HOW TO ADD NEW COMPRESSION TECHNIQUE
+//  ====================================
+//
+//  1. Creating your C++ compression class
+//
+//      1. Implement a new src/lib/OpenEXR/Imf*Compressor.{h, cpp} class deriving
+//         from ImfCompressor.
+//
+//      2. Update the build systems
+//          * Update src/lib/OpenEXR/CMakeLists.txt to build your codec with cmake.
+//          * Update BUILD.bazel to build your codec with bazel.
+//          * NOTE: Both build methods must be implemented !
+//
+//  2. C API integration
+//
+//      1. src/lib/OpenEXRCore/openexr_attr.h
+//          * Add your EXR_COMPRESSION_* to the exr_compression_t enum.
+//
+//      2. src/lib/OpenEXRCore/encoding.c
+//          * Update default_compress_chunk().
+//
+//      3. src/lib/OpenEXRCore/decoding.c
+//          * Update decompress_data().
+//
+//      4. src/lib/OpenEXRCore/parse_header.c
+//          * Update internal_exr_compute_chunk_offset_size().
+//
+//      5. src/lib/OpenEXRCore/validation.c
+//          * Update validate_deep_data()
+//
+//      6. Tests
+//
+//          1. src/test/OpenEXRCoreTest/compression.h
+//              * Declare your own test*Compression().
+//
+//          2. src/test/OpenEXRCoreTest/compression.cpp
+//              * Update doWriteRead().
+//              * Implement your test*Compression() function at the end.
+//
+//          3. src/test/OpenEXRCoreTest/main.cpp
+//              * Call your test function in main().
+//
+//          4. src/test/OpenEXRCoreTest/CMakeLists.txt
+//              * Add your test function name to define_openexrcore_tests().
+//
+//  3. C++ API integration
+//
+//      1. src/lib/OpenEXR/ImfCompression.h
+//         * Add your method at the end of the Compression enum below.
+//
+//      2. src/lib/OpenEXR/ImfCompression.cpp
+//          * Add your CompressionDesc(s) to IdToDesc[]. This is used by the API
+//             to check its capabilities and requirements.
+//             NOTE: the order MUST MATCH Compression's order, as we access the
+//                   descriptions by index.
+//           * Update CompressionNameToId to allow the API to map from your
+//             compressor's identifier(s) to its/their Compression value(s).
+//
+//      3. openexr/src/lib/OpenEXR/ImfCompressor.cpp
+//           * Include your Imf*Compressor.h.
+//           * Add your instantiation calls to newCompressor().
+//           * Add your instantiation calls to newTileCompressor().
+//
+//      4. src/lib/OpenEXR/ImfCRgbaFile.h
+//          * Add a IMF_*_COMPRESSION define for your compression method, making
+//            sure to update IMF_NUM_COMPRESSION_METHODS with the proper index.
+//
+//      5. Tests
+//
+//          1. src/test/OpenEXRTest/testCompressionApi.cpp
+//              * See the comments to update that file and ensure your method is
+//                properly registered.
+//
+//  4. Documentation
+//
+//      1. Compression methods are listed or described in many places throughout
+//         the docs and you will have to update all relevant *.rst files.
+//
+// -----------------------------------------------------------------------------
 
 #include "ImfNamespace.h"
 #include "ImfCompression.h"
@@ -37,22 +118,22 @@ struct CompressionDesc
 // clang-format off
 static const CompressionDesc IdToDesc[] = {
     CompressionDesc (
-        "none", 
-        "no compression.", 
-        1, 
-        false, 
+        "none",
+        "no compression.",
+        1,
+        false,
         true),
     CompressionDesc (
-        "rle", 
-        "run-length encoding.", 
-        1, 
-        false, 
+        "rle",
+        "run-length encoding.",
+        1,
+        false,
         true),
     CompressionDesc (
-        "zips", 
-        "zlib compression, one scan line at a time.", 
-        1, 
-        false, 
+        "zips",
+        "zlib compression, one scan line at a time.",
+        1,
+        false,
         true),
     CompressionDesc (
         "zip",

diff --git a/src/lib/OpenEXR/ImfCompression.h b/src/lib/OpenEXR/ImfCompression.h
@@ -13,7 +13,7 @@
 // This file enumerates available compression methods and defines a simple API
 // to query them.
 //
-//-----------------------------------------------------------------------------
+// ----------------------------------------------------------------------------
 
 #include "ImfForward.h"
 #include <string>