از 27 مارس 2025، توصیه می کنیم از android-latest-release به جای aosp-main برای ساختن و کمک به AOSP استفاده کنید. برای اطلاعات بیشتر، به تغییرات AOSP مراجعه کنید.
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
Android 13 یک کتابخانه استاتیک قابل تنظیم توسط فروشنده به نام libtonemap را معرفی می‌کند که عملیات نگاشت آهنگ را تعریف می‌کند و با فرآیند SurfaceFlinger و اجرای Hardware Composer (HWC) به اشتراک گذاشته می‌شود. این ویژگی OEM ها را قادر می سازد تا الگوریتم های نگاشت تن صفحه نمایش خود را بین چارچوب و فروشندگان تعریف و به اشتراک بگذارند و عدم تطابق در نگاشت آهنگ را کاهش دهد.
قبل از Android 13، عملیات نگاشت آهنگ مخصوص نمایشگر بین HWC، SurfaceFlinger و برنامه ها به اشتراک گذاشته نمی شد. بسته به مسیر رندر، برای محتوای HDR، این منجر به عدم تطابق در کیفیت تصویر می‌شود، جایی که محتوای HDR به روش‌های مختلف به فضای خروجی نگاشت می‌شود. این در سناریوهایی مانند چرخش صفحه، که در آن استراتژی ترکیب بندی بین GPU و DPU تغییر می کند، و در تفاوت در رفتار رندر بین TextureView و SurfaceView قابل درک بود.
این صفحه جزئیات رابط، سفارشی سازی و اعتبار سنجی کتابخانه libtonemap را شرح می دهد.
رابط به کتابخانه نقشه برداری تن
کتابخانه libtonemap شامل پیاده‌سازی‌های مبتنی بر CPU و سایه‌زن‌های SkSL است که می‌توانند توسط SurfaceFlinger برای ترکیب‌بندی GPU-backend و توسط HWC برای ایجاد جدول جستجوی نقشه تون (LUT) وصل شوند. نقطه ورود به libtonemapandroid::tonemap::getToneMapper() است، که شی ای را برمی گرداند که رابط ToneMapper پیاده سازی می کند.
رابط ToneMapper از قابلیت های زیر پشتیبانی می کند:
یک LUT نگاشت تن ایجاد کنید
رابط ToneMapper::lookupTonemapGain یک اجرای CPU از سایه زن تعریف شده در libtonemap_LookupTonemapGain() است. این توسط تست‌های واحد در چارچوب استفاده می‌شود، و می‌تواند توسط شرکا برای کمک به تولید یک LUT نگاشت تن در خط لوله رنگ خود استفاده شود.
libtonemap_LookupTonemapGain() مقادیر رنگ را در فضای خطی مطلق و غیرعادی، هم در RGB خطی و هم در XYZ می گیرد و یک شناور را برمی گرداند که توضیح می دهد چقدر رنگ های ورودی را در فضای خطی ضرب می کند.
یک سایه زن SkSL ایجاد کنید
رابط ToneMapper::generateTonemapGainShaderSkSL() یک رشته سایه زن SkSL را با توجه به فضای داده مبدا و مقصد برمی گرداند. سایه‌زن SkSL به پیاده‌سازی Skia برای RenderEngine ، مولفه ترکیب‌کننده با شتاب GPU برای SurfaceFlinger وصل شده است. سایه زن همچنین به libhwui وصل شده است، به طوری که نگاشت تون HDR به SDR می تواند به طور موثر برای TextureView انجام شود. از آنجایی که رشته تولید شده در سایر سایه زن های SkSL مورد استفاده Skia قرار می گیرد، شیدر باید قوانین زیر را رعایت کند:
رشته سایه زن باید یک نقطه ورودی با امضای float libtonemap_LookupTonemapGain(vec3 linearRGB, vec3 xyz) داشته باشد، جایی که linearRGB مقدار nit مطلق پیکسل های RGB در فضای خطی است و xyzlinearRGB است که به XYZ تبدیل می شود.
هر روش کمکی که توسط رشته سایه زن استفاده می شود باید با پیشوند رشته libtonemap_ باشد تا تعاریف سایه زن فریمورک با هم تضاد نداشته باشند. به طور مشابه، یونیفرم های ورودی باید با in_libtonemap_ پیشوند شوند.
یونیفرم های SkSL را تولید کنید
رابط ToneMapper::generateShaderSkSLUniforms() موارد زیر را با توجه به struct ابرداده ای که متادیتا را از استانداردهای مختلف HDR و شرایط نمایش توصیف می کند، برمی گرداند:
لیستی از یونیفرم هایی که توسط سایه زن SkSL محدود شده اند.
مقادیر یکسان in_libtonemap_displayMaxLuminance و in_libtonemap_inputMaxLuminance . این مقادیر توسط سایه بان های فریم ورک هنگام مقیاس بندی ورودی در libtonemap و عادی سازی خروجی در صورت لزوم استفاده می شود.
در حال حاضر فرآیند تولید یونیفرم نسبت به فضای داده ورودی و خروجی آگنوستیک است.
سفارشی سازی
پیاده سازی مرجع کتابخانه libtonemap نتایج قابل قبولی را تولید می کند. با این حال، از آنجا که الگوریتم نگاشت تن مورد استفاده توسط ترکیب GPU می‌تواند با الگوریتم مورد استفاده در ترکیب DPU متفاوت باشد، استفاده از پیاده‌سازی مرجع می‌تواند در برخی سناریوها مانند انیمیشن چرخش باعث سوسو زدن شود. سفارشی‌سازی می‌تواند چنین مشکلات کیفیت تصویر خاص فروشنده را حل کند.
OEM ها به شدت تشویق می شوند تا اجرای libtonemap را برای تعریف زیرکلاس ToneMapper خود که توسط getToneMapper() برگردانده می شود، نادیده بگیرند. هنگام سفارشی سازی پیاده سازی، از شرکا انتظار می رود یکی از موارد زیر را انجام دهند:
اجرای libtonemap را مستقیماً تغییر دهید.
کتابخانه استاتیک خود را تعریف کنید، کتابخانه را به صورت مستقل کامپایل کنید و فایل .a کتابخانه libtonemap را با فایلی که از کتابخانه سفارشی آنها تولید شده است جایگزین کنید.
فروشندگان نیازی به اصلاح هیچ کد هسته ای ندارند، اما چندین فروشنده باید جزئیات الگوریتم های نگاشت صدای DPU را برای پیاده سازی مناسب به اشتراک بگذارند.
اعتبار سنجی
این مراحل را برای تایید اجرای خود دنبال کنید:
ویدیوهای HDR را روی صفحه نمایش با استانداردهای HDR که سیستم نمایشگر شما پشتیبانی می کند ، مانند HLG، HDR10، HDR10+ یا DolbyVision پخش کنید.
ترکیب GPU را تغییر دهید تا مطمئن شوید که هیچ سوسو زدن قابل درک توسط کاربر وجود ندارد.
از دستور adb زیر برای تغییر ترکیب GPU استفاده کنید:
adb shell service call SurfaceFlinger 1008 i32 <0 to enable HWC composition,
1 to force GPU composition>
مسائل رایج
مشکلات زیر ممکن است با این پیاده سازی رخ دهد:
باندینگ زمانی ایجاد می شود که هدف رندر مورد استفاده توسط ترکیب GPU دقت کمتری نسبت به مقدار معمولی محتوای HDR داشته باشد. به عنوان مثال، باندبندی زمانی رخ می‌دهد که یک پیاده‌سازی HWC از فرمت‌های 10 بیتی مات برای HDR مانند RGBA1010102 یا P010 پشتیبانی می‌کند، اما نیاز دارد که ترکیب GPU برای پشتیبانی از آلفا در قالب 8 بیتی مانند RGBA8888 بنویسد.
اگر DPU با دقت متفاوتی نسبت به GPU کار کند، تغییر رنگ ظریف به دلیل تفاوت های کوانتیزاسیون ایجاد می شود.
هر یک از این مسائل مربوط به تفاوت های دقت نسبی سخت افزار زیرین است. یک راه حل معمولی این است که اطمینان حاصل شود که در مسیرهای با دقت پایین تر، یک گام پراکنده وجود دارد که باعث می شود تفاوت های دقیق کمتر قابل درک توسط انسان باشد.
محتوا و نمونه کدها در این صفحه مشمول پروانههای توصیفشده در پروانه محتوا هستند. جاوا و OpenJDK علامتهای تجاری یا علامتهای تجاری ثبتشده Oracle و/یا وابستههای آن هستند.
تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Tone Mapping HDR Luminance to an SDR-compatible Range\n\nAndroid 13 introduces a vendor-configurable static\nlibrary called `libtonemap`, which defines tone mapping operations and is shared\nwith the SurfaceFlinger process and Hardware Composer (HWC) implementations.\nThis feature enables OEMs to define and share their display tone mapping\nalgorithms between the framework and vendors, lessening a mismatch in tone\nmapping.\n\nPrior to Android 13, display-specific tone mapping\noperations weren't shared between the HWC, SurfaceFlinger, and apps. Depending\non the rendering path, for HDR content, this led to mismatches in image quality,\nwhere the HDR content was tone mapped to an output space in different ways. This\nwas perceptible in scenarios such as screen rotation, where the composition\nstrategy changes between the GPU and the DPU, and in differences in rendering\nbehavior between TextureView and SurfaceView.\n\nThis page describes the interface, customization, and validation details of the\n`libtonemap` library.\n| **Note:** Android 16 introduces a new HDR tone mapping method called Look-up Table (LUT) for HDR video outputs instead of using `libtonemap`. LUTs primarily resolve the fragmentation issue with HDR video outputs, especially for HLG and PQ, across a diverse range of Android devices. See the AIDL API [`android.hardware.graphics.composer3.DisplayLuts`](https://cs.android.com/android/platform/superproject/+/android-latest-release:hardware/interfaces/graphics/composer/aidl/android/hardware/graphics/composer3/DisplayLuts.aidl) for more information.\n\nInterface to the tone mapping library\n-------------------------------------\n\nThe [`libtonemap`](https://android.googlesource.com/platform/frameworks/native/+/refs/heads/android16-release/libs/tonemap/)\nlibrary contains CPU-backed implementations and SkSL shaders, which can be\nplugged in by SurfaceFlinger for GPU-backend composition and by the HWC for\ngenerating a tone mapping look-up table (LUT). The entry point to `libtonemap`\nis [`android::tonemap::getToneMapper()`](https://android.googlesource.com/platform/frameworks/native/+/refs/heads/android16-release/libs/tonemap/tonemap.cpp#733), which returns an object that\nimplements the [`ToneMapper`](https://android.googlesource.com/platform/frameworks/native/+/refs/heads/android16-release/libs/tonemap/include/tonemap/tonemap.h#86) interface.\n\nThe `ToneMapper` interface supports the following capabilities:\n\n- Generate a tone-mapping LUT\n\n The interface [`ToneMapper::lookupTonemapGain`](https://android.googlesource.com/platform/frameworks/native/+/refs/heads/android16-release/libs/tonemap/include/tonemap/tonemap.h#147) is a CPU\n implementation of the shader defined in `libtonemap_LookupTonemapGain()`. This\n is used by unit tests in the framework, and can be used by partners for\n assistance with generating a tone-mapping LUT inside their color pipeline.\n\n `libtonemap_LookupTonemapGain()` takes in color values in absolute,\n unnormalized linear space, both in linear RGB and in XYZ, and returns a float\n describing how much to multiply the input colors in linear space.\n- Generate an SkSL shader\n\n The interface [`ToneMapper::generateTonemapGainShaderSkSL()`](https://android.googlesource.com/platform/frameworks/native/+/refs/heads/android16-release/libs/tonemap/include/tonemap/tonemap.h#122) returns an\n SkSL shader string, given a source and destination dataspace. The SkSL shader is\n plugged into the Skia implementation for [`RenderEngine`](https://cs.android.com/android/platform/superproject/+/android-latest-release:frameworks/native/libs/renderengine/),\n the GPU-accelerated compositing component for SurfaceFlinger. The shader is also\n plugged into [`libhwui`](https://cs.android.com/android/platform/superproject/+/android-latest-release:frameworks/base/libs/hwui),\n so that HDR-to-SDR tone mapping can be performed efficiently for `TextureView`.\n Because the generated string is in-lined into other SkSL shaders used by Skia,\n the shader must adhere to the following rules:\n - The shader string must have an entry point with the `float libtonemap_LookupTonemapGain(vec3 linearRGB, vec3 xyz)` signature, where `linearRGB` is the value of the absolute nits of the RGB pixels in linear space and `xyz` is `linearRGB` converted into XYZ.\n - Any helper methods used by the shader string must be prefixed with the string `libtonemap_` so that framework shader definitions don't conflict. Similarly, input uniforms must be prefixed with `in_libtonemap_`.\n- Generate SkSL uniforms\n\n The interface [`ToneMapper::generateShaderSkSLUniforms()`](https://android.googlesource.com/platform/frameworks/native/+/refs/heads/android16-release/libs/tonemap/include/tonemap/tonemap.h#136) returns the\n following, given a metadata `struct` describing metadata from different HDR\n standards and display conditions:\n - A list of uniforms that are bound by an SkSL shader.\n\n - The uniform values `in_libtonemap_displayMaxLuminance` and\n `in_libtonemap_inputMaxLuminance`. These values are used by framework shaders\n when scaling the input into `libtonemap`, and normalizing the output as\n applicable.\n\n Currently the process of generating uniforms is agnostic to the input and\n output dataspace.\n\n### Customization\n\nThe reference implementation of the [`libtonemap`](https://android.googlesource.com/platform/frameworks/native/+/refs/heads/android16-release/libs/tonemap/) library produces acceptable results. However,\nbecause the tone mapping algorithm used by GPU composition can differ from that\nused by the DPU composition, using the reference implementation can cause\nflicker in some scenarios such as the rotation animation. Customization can\nresolve such vendor-specific image quality issues.\n\nOEMs are strongly encouraged to override the implementation of `libtonemap` to\ndefine their own `ToneMapper` subclass, which is returned by `getToneMapper()`.\nWhen customizing the implementation, partners are expected to do one of the\nfollowing:\n\n- Modify the implementation of `libtonemap` directly.\n- Define their own static library, compile the library as a standalone, and replace `libtonemap` library's `.a` file with the one generated from their custom library.\n\nVendors don't need to modify any kernel code, but multiple vendors must\ncommunicate details about the DPU tone-mapping algorithms for proper\nimplementation.\n\n### Validation\n\nFollow these steps to validate your implementation:\n\n1. Play HDR videos on screen of any HDR standards that your [display system supports](https://developer.android.com/reference/android/view/Display#getHdrCapabilities()),\n such as HLG, HDR10, HDR10+, or DolbyVision.\n\n2. Toggle GPU composition to ensure that there's no user perceptible flicker.\n\n Use the following `adb` command to toggle the GPU composition: \n\n adb shell service call SurfaceFlinger 1008 i32 \u003c0 to enable HWC composition,\n 1 to force GPU composition\u003e\n\n### Common issues\n\nThe following issues can occur with this implementation:\n\n- Banding is caused when the render target used by GPU composition is of lower\n precision than the typical value for HDR content. For instance, banding can\n occur when an HWC implementation supports opaque 10-bit formats for HDR such as\n RGBA1010102 or P010, but requires that GPU composition writes to an 8-bit format\n like RGBA8888 to support alpha.\n\n- A subtle color shift is caused by quantization differences if the DPU\n operates at a different precision than the GPU.\n\nEach of these issues is related to the relative precision differences of the\nunderlying hardware. A typical workaround is to ensure that there's a dithering\nstep in the lower precision paths, making any precision differences less human\nperceptible."]]
