Hook decoder fusion up to the decompression process (#516)

include/openzl/zl_decompress.h

@@ -125,6 +125,18 @@ typedef enum {
      */
     ZL_DParam_checkContentChecksum = 3,
 
+    /**
+     * @brief Enable codec fusion during decompression.
+     *
+     * Codec fusion combines multiple adjacent codec nodes into a single
+     * optimized decoder. Setting this to ZL_TernaryParam_disable causes each
+     * codec in the graph to be decoded individually, which can be useful for
+     * debugging or testing codec correctness without fusion.
+     *
+     * Valid values use the ZL_TernaryParam format defaulting to enabled.
+     */
+    ZL_DParam_enableCodecFusion = 4,
+
 } ZL_DParam;
 
 /**

src/openzl/codecs/decoder_registry.c

@@ -169,4 +169,8 @@ const StandardDTransform SDecoders_array[ZL_StandardTransformID_end] = {
     REGISTER_DEPRECATED_TTRANSFORM_G(ZL_StandardTransformID_huffman_deprecated, 3, 14, DI_HUFFMAN, PIPE_GRAPH),
     REGISTER_DEPRECATED_TTRANSFORM_G(ZL_StandardTransformID_huffman_fixed_deprecated, 3, 14, DI_HUFFMAN_FIXED, FIXED_ENTROPY_GRAPH),
 };
+
+const ZL_DecoderFusionDesc ZL_DecoderFusion_array[ZL_DecoderFusionID_end + 1] = {
+    { { 0 }, NULL },
+};
 // clang-format on

src/openzl/codecs/decoder_registry.h

@@ -3,7 +3,8 @@
 #ifndef ZSTRONG_TRANSFORMS_DECODER_REGISTRY_H
 #define ZSTRONG_TRANSFORMS_DECODER_REGISTRY_H
 
-#include "openzl/common/wire_format.h"     // ZL_StandardTransformID_end
+#include "openzl/common/wire_format.h" // ZL_StandardTransformID_end
+#include "openzl/decompress/decoder_fusion.h"
 #include "openzl/decompress/dtransforms.h" // DTransform, DTrDesc
 #include "openzl/shared/portability.h"
 
@@ -17,6 +18,18 @@ typedef struct {
 
 extern const StandardDTransform SDecoders_array[ZL_StandardTransformID_end];
 
+/// IDs for the built-in decoder fusions. New fusions should be added before
+/// ZL_DecoderFusionID_end.
+typedef enum {
+    ZL_DecoderFusionID_end,
+} ZL_DecoderFusionID;
+
+/// The built-in decoder fusion descriptors, indexed by ZL_DecoderFusionID.
+/// TODO: Remove the +1 once ZL_DecoderFusion_end != 0.
+/// It is needed because zero-lengthed arrays are not standard C.
+extern const ZL_DecoderFusionDesc
+        ZL_DecoderFusion_array[ZL_DecoderFusionID_end + 1];
+
 ZL_END_C_DECLS
 
 #endif

src/openzl/decompress/dctx2.h

@@ -125,6 +125,47 @@ ZL_Report DCtx_setAppliedParameters(ZL_DCtx* dctx);
 
 int DCtx_getAppliedGParam(const ZL_DCtx* dctx, ZL_DParam gdparam);
 
+/// Sentinel value indicating a stream is stored in the frame rather than
+/// produced by a decoder node.
+#define ZL_PRODUCER_STORE ((ZL_IDType)(-1))
+
+typedef struct ZL_AppendToOutputOptimization_s ZL_AppendToOutputOptimization;
+
+typedef struct ZL_DecoderFusionDesc_s ZL_DecoderFusionDesc;
+
+/// Metadata about a single data stream in the decompression context.
+typedef struct ZL_DCtx_DataInfo {
+    ZL_Data* data;
+    ZL_AppendToOutputOptimization* appendOpt;
+    /// The index of the node that produced this stream or
+    /// ZL_PRODUCER_STORE if stored in the frame.
+    ZL_IDType producerNodeIdx;
+} ZL_DCtx_DataInfo;
+
+/**
+ * Run the decoder for a single node.
+ *
+ * @param nodeInfo The node to run.
+ * @param withinFusedDecoder If true, this function is being called from within
+ * a currently executing decoder fusion via ZL_DecoderFusion_runCodec(), so do
+ * not search for decoder fusions as the caller is explicitly asking for the
+ * codec to be executed.
+ */
+ZL_Report DCTX_runDecoder(
+        ZL_DCtx* dctx,
+        const DFH_NodeInfo* nodeInfo,
+        bool withinFusedDecoder);
+
+/// Register a decoder fusion with the decompression context.
+/// @see ZL_DecoderFusionState_registerFusion()
+ZL_Report DCTX_registerDecoderFusion(
+        ZL_DCtx* dctx,
+        const ZL_DecoderFusionDesc* fusion);
+
+/// Remove all registered decoder fusions from the decompression context.
+/// @see ZL_DecoderFusionState_clearFusions()
+void DCTX_clearDecoderFusions(ZL_DCtx* dctx);
+
 ZL_END_C_DECLS
 
 #endif // ZSTRONG_DECOMPRESS_DCTX2_H

src/openzl/decompress/decode_frameheader.h

@@ -18,6 +18,7 @@ ZL_BEGIN_C_DECLS
 // ZL_Report ZL_getHeaderSize(const void* src, size_t srcSize)
 
 /* Non-public symbols exposed by this unit */
+typedef struct ZL_DecoderFusionDesc_s ZL_DecoderFusionDesc;
 
 typedef struct {
     PublicTransformInfo trpid;
@@ -39,6 +40,11 @@ typedef struct {
      * @note Set by the dctx after decoding the frame header.
      */
     uint32_t numInputStreams;
+    /**
+     * If this node is fused, a pointer to the fusion descriptor.
+     * @note Set by the dctx after decoding the frame header.
+     */
+    const ZL_DecoderFusionDesc* fusion;
 } DFH_NodeInfo;
 
 DECLARE_VECTOR_TYPE(DFH_NodeInfo)