Skip to content

Align SimdLib.h API docs with actual behavior for gradient, feature-difference, and alpha pipelines#356

Merged
ermig1979 merged 2 commits into
masterfrom
copilot/improve-function-descriptions
May 26, 2026
Merged

Align SimdLib.h API docs with actual behavior for gradient, feature-difference, and alpha pipelines#356
ermig1979 merged 2 commits into
masterfrom
copilot/improve-function-descriptions

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented May 26, 2026

The issue was outdated/inexact descriptions in SimdLib.h for several image-processing APIs, especially around feature-difference math and alpha compositing semantics. This update rewrites those docs to match implementation-level behavior and parameter meaning.

  • Abs gradient + feature difference semantics

    • Updated SimdAbsGradientSaturatedSum wording to explicitly describe saturated |dx| + |dy| behavior and border handling.
    • Corrected SimdAddFeatureDifference formula to the implementation’s actual excess term and saturating accumulation:
      • excess = max(max(value - hi, lo - value), 0)
      • difference = min(difference + ((weight * excess * excess) >> 16), 255)
  • Alpha blending family clarified

    • Reworded SimdAlphaBlending, SimdAlphaBlending2x, SimdAlphaBlendingUniform, and SimdAlphaFilling around true per-channel equations.
    • Explicitly documented DivideBy255 rounding form used by implementation instead of plain /255 shorthand.
  • BGRA → YUV420p alpha path documented precisely

    • Updated SimdAlphaBlendingBgraToYuv420p docs to reflect real behavior:
      • Y: per-pixel BGR→Y then alpha blend with destination Y.
      • U/V: 2x2-averaged BGR and averaged alpha, then blend with destination U/V.
  • Premultiply / unpremultiply channel-layout behavior

    • Refined SimdAlphaPremultiply and SimdAlphaUnpremultiply descriptions to reflect:
      • alpha-channel preservation,
      • clamp behavior on unpremultiply,
      • argb-controlled alpha index (3 for BGRA/RGBA, 0 for ARGB).
// SimdAddFeatureDifference (documented to match implementation):
excess = max(max(value[i] - hi[i], lo[i] - value[i]), 0);
difference[i] = min(difference[i] + ((weight * excess * excess) >> 16), 255);

Copilot AI and others added 2 commits May 26, 2026 07:07
@ermig1979 ermig1979 marked this pull request as ready for review May 26, 2026 07:49
Copilot AI review requested due to automatic review settings May 26, 2026 07:49
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the public C API documentation in SimdLib.h to accurately reflect the library’s implemented behavior for CRC, absolute-difference/gradient, feature-difference accumulation, and multiple alpha blending / alpha conversion pipelines.

Changes:

  • Clarifies CRC-32 / CRC-32C parameters (polynomial form, init/final XOR semantics) and tightens wording.
  • Aligns gradient and feature-difference documentation with implementation details (including saturation/clamping and exact formulas).
  • Documents alpha blending math using the library’s DivideBy255 rounding form and clarifies BGRA→YUV420p alpha blending semantics and premultiply/unpremultiply channel layout behavior.

@ermig1979 ermig1979 merged commit 45c20da into master May 26, 2026
23 of 25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants