ImageKnifePro 源码解读(四):降采样策略族——按显示尺寸改衣服,不按原尺寸硬塞

ImageKnifePro 源码解读(四):降采样策略族------按显示尺寸改衣服,不按原尺寸硬塞

先看一张 4K 图有多占内存

一张 4096×3072 的照片,解码成 RGBA 位图进内存:

yaml 复制代码
4096 × 3072 × 4 字节 ≈ 48 MB

一张照片就 48MB。你的图片列表一屏显示 12 张,如果全部按原尺寸解码,576MB 就没了------中低端机直接 OOM。

所以降采样不是可选项,是必选项。但问题来了:降到多少?怎么降?不同场景该用哪种策略?

ImageKnifePro 的答案是策略族:不是一个固定的降采样算法,而是一组可插拔的策略,按场景选。默认、期望尺寸、内存优先、质量优先、上限、下限......每种场景都有对应的打法。

本文内容 :拆解这个策略族------DownSamplingBase 的因子计算为什么取 2 的幂、DownSampler 的策略映射表长什么样、desired 怎么按期望尺寸精确采样、fit_center 和 center_inside 的内存优先与质量优先有何区别、以及不同图片格式(PNG/WEBP)的取整差异。读完你会确切知道:原图是怎么被"按显示尺寸改小"的、为什么降采样因子是 2 的幂、以及你的场景该选哪种策略。

📦 仓库地址 | 本文基于 v1.0.16 及之后版本 源码根目录:library/src/main/cpp/,下文路径均相对于此。


一、先建立图景:裁缝改衣服

把降采样想象成裁缝改衣服:

  • 原图是一件大码衣服(4K、8K 原图)。
  • 你的 Image 组件是要穿衣服的人,尺寸固定(比如 300×200 像素)。
  • 降采样就是按人的尺寸把衣服改小,而不是把大码衣服硬塞进去。

但"改小"不是一刀切,有几种改法:

改法 对应策略 适用场景
按身高精确改到某个尺寸 desired 你已经知道组件要多大,按期望尺寸采样
尽量改小省布料,能穿就行 fit_center_memory 内存紧张,优先省内存
改小但尽量保持版型好看 fit_center_quality 内存够,优先显示质量
改到不小于某个尺寸 at_least 不能缩得太小,保底清晰度
改到不超过某个尺寸 at_most 不能超过上限,防止过大
按默认规则改 default 没特殊要求时的常规处理

核心原则:按"人"的尺寸改,不是按"衣服"的尺寸改。 这就是为什么降采样能省内存------你根本不需要把 4K 全量数据放进内存,只需要 300×200 那一小块。


二、DownSamplingBase:策略基类与 2 的幂因子

所有策略都继承自 DownSamplingBase,它定义了怎么算缩放因子。

📄 downsampling/down_sampling_base.h

cpp 复制代码
class DownSamplingBase {
public:
    virtual float GetScaleFactor(const Image_Size &sourceSize, const Image_Size &requestSize) = 0;
    virtual ~DownSamplingBase() = default;

protected:
    uint32_t GetFactorAsBit(uint32_t num)
    {
        uint32_t res = HighestOneBit(num);
        return res > 1 ? res : 1;
    }

    float GetFactor(const Image_Size &sourceSize, const Image_Size &requestSize)
    {
        uint32_t maxIntFactor = std::max(sourceSize.width / requestSize.width,
                                         sourceSize.height / requestSize.height);
        return maxIntFactor == 0 ? 1.0 : 1.0 / HighestOneBit(maxIntFactor);
    }

private:
    // 找出给定整数中最高位的 1 所代表的值(1、2、4、8、16...)
    uint32_t HighestOneBit(uint32_t num)
    {
        int pos = 1;
        const int count = 5;
        for (int i = 0; i < count; i++) {
            num |= (num >> pos);
            pos += pos;
        }
        return num - (num >> 1);
    }
};

GetFactor 的计算逻辑:

  1. 分别算宽和高的整数倍缩放比:sourceSize.width / requestSize.width、sourceSize.height / requestSize.height
  2. 取两者中较大的那个 maxIntFactor(保证改完能装下)
  3. 返回 1.0 / HighestOneBit(maxIntFactor)

HighestOneBit 是取 2 的幂:它用位运算把整数向下填充,最后得到最高位的 1 代表的值。比如:

  • maxIntFactor = 12 → HighestOneBit(12) = 8 → 因子 = 1/8
  • maxIntFactor = 5 → HighestOneBit(5) = 4 → 因子 = 1/4

为什么因子要取 2 的幂? 因为2 的幂缩放可以用位移和快速算法实现,比任意浮点缩放快得多,也更不容易产生缩放失真。这是性能与质量的权衡:宁可多缩一点(1/8 而不是 1/12),也要保证缩放快且稳。

GetFactorAsBit 还保证 res > 1 ? res : 1,即最小缩放因子是 1------不会把图缩成 0 或负数。


三、策略族总览:DownSampler 的映射表

DownSampler 用一个静态映射表把策略枚举映射到具体实现:

📄 downsampling/down_sampler.h

cpp 复制代码
static DownSamplingBase *GetDownSampling(DownSamplingStrategy strategy)
{
    static std::unordered_map<DownSamplingStrategy, DownSamplingBase *> downSamplerMap = {
        {DownSamplingStrategy::NONE, nullptr},
        {DownSamplingStrategy::DEFAULT, new DownSamplingDefault()},
        {DownSamplingStrategy::FIT_CENTER_MEMORY, new DownSamplingFitCenterMemory()},
        {DownSamplingStrategy::FIT_CENTER_QUALITY, new DownSamplingFitCenterQuality()},
        {DownSamplingStrategy::CENTER_INSIDE_MEMORY, new DownSamplingCenterInside(true)},
        {DownSamplingStrategy::CENTER_INSIDE_QUALITY, new DownSamplingCenterInside(false)},
        {DownSamplingStrategy::AT_LEAST, new DownSamplingAtLeast()},
        {DownSamplingStrategy::AT_MOST, new DownSamplingAtMost()},
        {DownSamplingStrategy::DESIRED_SIZE_FILL, new DownSamplingDesired(DownSamplingStrategy::DESIRED_SIZE_FILL)},
        {DownSamplingStrategy::DESIRED_SIZE_ASPECT_FIT,
         new DownSamplingDesired(DownSamplingStrategy::DESIRED_SIZE_ASPECT_FIT)},
        {DownSamplingStrategy::DESIRED_SIZE_ASPECT_FILL,
         new DownSamplingDesired(DownSamplingStrategy::DESIRED_SIZE_ASPECT_FILL)}
    };

    return downSamplerMap[strategy];
}

策略与实现是一一对应的表驱动 。你传一个策略枚举,它返回对应的 DownSamplingBase 指针。

CalculateSize 是统一入口:

📄 downsampling/down_sampler.h

cpp 复制代码
static Image_Size CalculateSize(ImageFormat format, Image_Size sourceSize, Image_Size requestSize,
                                DownSamplingStrategy strategy)
{
    if (format == ImageFormat::SVG) {
        return imageSize;   // SVG 是矢量图,不需要降采样
    }

    DownSamplingBase *downSampling = GetDownSampling(strategy);
    if (downSampling == nullptr) return imageSize;

    // 期望尺寸策略走专门的 CalculateDecodeSize
    if (DownSamplingDesired::IsDesiredSizeStrategy(strategy)) {
        auto *desired = static_cast<DownSamplingDesired *>(downSampling);
        return desired->CalculateDecodeSize(format, sourceSize, requestSize);
    }

    // 非默认策略且宽高未知,不计算
    if ((requestSize.width == 0 || requestSize.height == 0) && strategy != DownSamplingStrategy::DEFAULT) {
        return imageSize;
    }

    float scaleFactor = downSampling->GetScaleFactor(sourceSize, requestSize);

    // 不同格式用不同取整方式
    if (format == ImageFormat::PNG) {
        imageSize.width = std::floor(sourceSize.width / scaleFactor);
        imageSize.height = std::floor(sourceSize.height / scaleFactor);
    } else if (format == ImageFormat::WEBP) {
        imageSize.width = std::round(sourceSize.width / scaleFactor);
        imageSize.height = std::round(sourceSize.height / scaleFactor);
    } else {
        imageSize.width = sourceSize.width / scaleFactor;
        imageSize.height = sourceSize.height / scaleFactor;
    }
    return imageSize;
}

三个细节:

  • SVG 直接返回:矢量图按描述绘制,不存在"解码成大位图"的问题,不需要降采样。
  • 非默认策略且宽高未知时不计算 :requestSize 为 0 时,除默认策略外都不做降采样计算,避免除零或无意义缩放。
  • 不同格式取整不同 :PNG 用 std::floor(向下取整),WEBP 用 std::round(四舍五入),其他格式直接除。这是为了适配不同格式的解码特性------PNG 向下取整避免尺寸超过预期,WEBP 四舍五入保精度。

四、desired:按期望尺寸精确采样

desired 策略是最实用的------你明确知道组件要多大,就按那个尺寸采样。

📄 downsampling/down_sampling_desired.h

cpp 复制代码
struct DesiredSizeRequest {
    Image_Size requestSize;
    DownSamplingStrategy effectiveStrategy;
};

class DownSamplingDesired : public DownSamplingBase {
public:
    explicit DownSamplingDesired(DownSamplingStrategy strategy);

    float GetScaleFactor(const Image_Size &sourceSize, const Image_Size &requestSize) override;

    Image_Size CalculateDecodeSize(ImageFormat format, const Image_Size &sourceSize,
        const Image_Size &requestSize) const;

    static bool IsDesiredSizeStrategy(DownSamplingStrategy strategy);
    static bool IsDesiredSizeValid(const Image_Size &desiredSize);

    static DesiredSizeRequest BuildDesiredSizeRequest(Image_Size componentSize,
        const std::shared_ptr<ImageKnifeOption> &option);

private:
    DownSamplingStrategy strategy_;
};

CalculateDecodeSize 是 desired 策略专用的解码尺寸计算 ,区别于其他策略的 GetScaleFactor------它不仅算缩放因子,还直接算出最终解码尺寸。

IsDesiredSizeStrategy 用于在 CalculateSize 里识别:"这是不是期望尺寸策略?是的话走 CalculateDecodeSize,不是的话走通用因子计算"。

BuildDesiredSizeRequest 则从 componentSize(组件尺寸)和 option(用户配置)构造请求------这就是"按人的尺寸改衣服"的落地:组件多大,就按多大去算解码尺寸。

desired 有三个变体,对应不同的填充方式:

变体 含义
DESIRED_SIZE_FILL 按期望尺寸填满,可能拉伸变形
DESIRED_SIZE_ASPECT_FIT 保持宽高比,完整显示在期望尺寸内(可能留边)
DESIRED_SIZE_ASPECT_FILL 保持宽高比,填满期望尺寸(可能裁剪)

这三种覆盖了"精确尺寸"的三种常见诉求:要么不顾比例填满、要么完整显示、要么裁满。你可以按 UI 要求选。


五、fit_center 与 center_inside:内存优先 vs 质量优先

这两组策略解决的是**"省内存"和"保质量"的取舍**。

📄 downsampling/down_sampler.h(映射表)

cpp 复制代码
{DownSamplingStrategy::FIT_CENTER_MEMORY, new DownSamplingFitCenterMemory()},
{DownSamplingStrategy::FIT_CENTER_QUALITY, new DownSamplingFitCenterQuality()},
{DownSamplingStrategy::CENTER_INSIDE_MEMORY, new DownSamplingCenterInside(true)},
{DownSamplingStrategy::CENTER_INSIDE_QUALITY, new DownSamplingCenterInside(false)},
  • fit_center_memory:内存优先------尽量多缩,省内存,适合长列表、低端机。
  • fit_center_quality:质量优先------少缩一点,保证显示质量,适合详情页、高清展示。
  • center_inside(true):中心裁剪 + 内存优先。
  • center_inside(false):中心裁剪 + 质量优先。

"fit_center" 和 "center_inside" 的区别:

  • fit_center 是适配居中------把图缩到能放进组件,居中显示,可能留边(aspect fit)。
  • center_inside 是中心裁剪------把图缩到能盖住组件,从中心裁剪多余部分(aspect fill)。

"内存优先"和"质量优先"影响的是缩放因子的选择:同样的源尺寸和请求尺寸,内存优先会选更小的因子(缩得更多),质量优先会选更大的因子(缩得更少、更清晰)。

怎么选:

  • 列表页、快速滑动、图多 → 选 *_MEMORY
  • 详情页、摄影社区、需要看细节 → 选 *_QUALITY
  • 要完整看到整图 → fit_center
  • 要铺满组件、可接受裁边 → center_inside

六、at_least 与 at_most:下限与上限

这两个策略给缩放设边界:

  • at_least :至少保留某个尺寸,不能缩得太小------保证清晰度下限。
  • at_most :最多缩到某个尺寸,不能超过上限------防止图片过大。

📄 downsampling/down_sampler.h(映射表)

cpp 复制代码
{DownSamplingStrategy::AT_LEAST, new DownSamplingAtLeast()},
{DownSamplingStrategy::AT_MOST, new DownSamplingAtMost()},

at_least 适合"不能糊"的场景:比如头像、图标,再小也不能低于可辨识的清晰度。

at_most 适合"不能超"的场景:比如列表缩略图,最大只能显示到某个尺寸,再大的原图也得压下来。

它们和 desired 的区别是:desired 是"精确到某个尺寸",at_least/at_most 是"限制在某个范围"。一个管精确值,一个管上下界。


七、不同格式的取整差异

前面提到 CalculateSize 里 PNG 用 floor、WEBP 用 round,这个细节值得单独说。

📄 downsampling/down_sampler.h

cpp 复制代码
if (format == ImageFormat::PNG) {
    imageSize.width = std::floor(sourceSize.width / scaleFactor);
    imageSize.height = std::floor(sourceSize.height / scaleFactor);
} else if (format == ImageFormat::WEBP) {
    imageSize.width = std::round(sourceSize.width / scaleFactor);
    imageSize.height = std::round(sourceSize.height / scaleFactor);
} else {
    imageSize.width = sourceSize.width / scaleFactor;
    imageSize.height = sourceSize.height / scaleFactor;
}

为什么 PNG 要向下取整? PNG 是无损格式,像素是精确的。向下取整可以保证解码后的尺寸不超过预期,避免内存超出预估。

为什么 WEBP 要四舍五入? WEBP 是有损压缩,本身就有精度损失。四舍五入能让尺寸更接近理想值,在不超内存的前提下尽量保住清晰度。

其他格式直接除,不做额外取整------这是默认行为,按浮点结果转整数。

这个细节说明:降采样不是单纯的数学缩放,还要考虑不同格式的解码特性。同样是改小,无损和有损的处理方式不一样。


八、回到最初的问题:降采样如何防 OOM

开头的疑问是"4K 原图 48MB,几张就 OOM",现在可以完整回答这套策略族怎么解决:

机制 作用 效果
按显示尺寸采样 只解码组件需要的那一小块 4K 原图 → 300×200,内存从 48MB 降到几百 KB
因子取 2 的幂 HighestOneBit 得到 2 的幂因子 缩放可用快速算法,且不失真
策略族可选 内存优先/质量优先/期望尺寸/上下限 不同场景选不同策略,不硬套一种
格式差异处理 PNG floor、WEBP round、SVG 跳过 适配不同格式特性,不超内存且保清晰
缓存键含降采样信息 downSamplingInfo 进 MemoryKeyParams 不同采样结果分开缓存,不混用

一句话总结 :降采样不是"把图缩小",而是"按显示尺寸精确改衣服"------只把组件需要的那部分解码进内存,其余不碰。 48MB 的原图因此变成几百 KB,OOM 自然解决了。

对使用者的三条实用结论:

  1. 列表页用内存优先策略(*_MEMORY),详情页用质量优先策略(*_QUALITY)。图多的时候内存是第一位的,看细节的时候质量是第一位的。
  2. 明确知道组件尺寸就用 desired 。DESIRED_SIZE_FILL 填满、ASPECT_FIT 完整显示、ASPECT_FILL 裁满,按 UI 要求选。
  3. 注意不同采样结果要分开缓存 。如果你动态改采样尺寸,确保缓存键里的 downSamplingInfo 跟着变,否则会拿到旧尺寸的图。

下一篇讲 Native 渲染节点与 ArkTS 组件的协作:ImageKnifeComponent 的 build() 为什么只有一行 ContentSlot、C++ 层是怎么创建和管理 Image 节点的、以及 aboutToRecycle 和 aboutToDisappear 的区别为什么重要。


项目地址:ImageKnifePro

相关推荐
民办二本的神29 分钟前
AI 助手升级后聊天记录又丢了(二):数据一直都在,丢的是"看见"
harmonyos
huang_xiaoen19 小时前
鸿蒙手机远程控制电脑哪个好用?2026鸿蒙远控软件横测推荐
华为·harmonyos·远程工作·远程工具·远程办公
爱写Bug的浮游2 天前
初识仓颉:5 分钟看懂核心语法
harmonyos·编程语言
程序猿追3 天前
鸿蒙 PC 的 Ionic 工单有两个错误,按下生成后光标该去哪儿
华为·harmonyos
KevinChaos3 天前
随手备忘录手记 04|HarmonyOS 7.0新特性实验:物品图鉴的加载逻辑
华为·harmonyos
Sirius_Ji3 天前
从硬解基座到字幕与滤镜链:ffmpeg-for-HarmonyOS v0.3.2
harmonyos
用户86194177207413 天前
uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"
微信·harmonyos
码间留白3 天前
uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"
uni-app·harmonyos·鸿蒙·uts插件·微信商家转账
GitCode官方4 天前
开源鸿蒙跨平台直播|AI 时代,用 cj-tauri 开发鸿蒙 PC 应用
人工智能·华为·harmonyos·atomgit