# Задача: иконка приложения строго по собственному силуэту, без системной маски

## Цель

- Иконка приложения нигде не обрезается системной маской формы (круг, скруглённый квадрат, squircle и т. п.).
- Там, где не-adaptive иконка рисуется без дополнительной обработки (собственный лаунчер проекта, если он есть, а также сторонние лаунчеры, которые не оборачивают такие иконки), она отображается строго по контуру самого изображения и не меняется при смене формы иконок в системе или в лаунчере.

## Принцип

На Android 8+ маску формы получают только иконки типа `AdaptiveIconDrawable` (`<adaptive-icon>`). Поэтому ни один вариант ресурса иконки приложения не должен быть adaptive. `android:icon` должен разрешаться в обычный bitmap (PNG с альфа-каналом), в котором форма уже «запечена»: внутри контура непрозрачная заливка, снаружи полностью прозрачные пиксели.

Часть стоковых поверхностей AOSP сама оборачивает не-adaptive иконки в adaptive с подложкой. Со стороны приложения это не отключается (см. «Ограничения»).

Референсная реализация: https://github.com/wolk-tambowskij/blownchart, ветка `15-dev`:

- коммит `7223b40d3a`: растр с запечённой формой + обход маски внутри самого лаунчера;
- коммит `e4ea819a5b`: манифест и `mipmap-anydpi-v26` переведены с `<adaptive-icon>` на `<bitmap>`;
- файлы: `res/drawable/ic_launcher_home.xml`, `res/mipmap-anydpi-v26/ic_launcher_home.xml`, `res/mipmap-anydpi-v26/ic_launcher_home_round.xml`, `res/mipmap-*/ic_launcher_home_true_shape.png`, `lawnchair/src/app/blownchart/icons/BlownChartIconProvider.kt`.

Ниже `<icon>` обозначает имя ресурса иконки в целевом проекте.

## 1. Растр с запечённой формой

Файл `res/mipmap-<density>/<icon>_true_shape.png`, формат RGBA, во всех плотностях (холст 108 dp, как в референсе):

| Папка | Размер, px |
|---|---|
| `mipmap-mdpi` | 108 × 108 |
| `mipmap-hdpi` | 162 × 162 |
| `mipmap-xhdpi` | 216 × 216 |
| `mipmap-xxhdpi` | 324 × 324 |
| `mipmap-xxxhdpi` | 432 × 432 |

Требования к изображению:

- Снаружи контура alpha = 0, внутри alpha = 255, на кромке сглаживание (промежуточные значения alpha).
- Силуэт вписан в холст почти вплотную, без лишних прозрачных полей. В референсе bounding box непрозрачной области: 5…428 × 21…411 на холсте 432 px, то есть отступ около 1 % по большей стороне. «Настройки» и «Недавние» рисуют bitmap в рамку иконки как есть, поэтому поля визуально уменьшат иконку.
- Исходник: существующий арт иконки. Если сейчас иконка adaptive, исходник — композиция слоёв `background` + `foreground`; слой `monochrome` не используется.
- Прозрачность снаружи получать по фактическому контуру фигуры: заливкой от краёв холста или трассировкой внешнего контура. Порог по цвету («близко к фону → прозрачно») не применять: в референсе он выбил белую заливку внутри фигуры, что пришлось исправлять в `7223b40d3a`.
- Если контур из исходника однозначно не определяется (например, фон залит на весь квадрат и силуэта нет), форму не придумывать. Остановиться и запросить PNG с прозрачностью.

## 2. Ресурсы

`res/drawable/<icon>.xml`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<bitmap xmlns:android="http://schemas.android.com/apk/res/android"
    android:src="@mipmap/<icon>_true_shape" />
```

Все XML-варианты иконки в папках `mipmap-anydpi*` и `drawable-anydpi*` (`mipmap-anydpi-v26`, `mipmap-anydpi` без квалификатора версии, `-v33` и т. п.), включая `<icon>_round.xml`, которые сейчас содержат `<adaptive-icon>`: заменить их содержимое тем же `<bitmap>`, что выше. Вариант: удалить их, если на них больше ничего не ссылается. На API 26+ квалификатор `anydpi-v26` выигрывает у папок по плотностям, поэтому одна оставшаяся `<adaptive-icon>` в цепочке вернёт маску.

Проверить все source sets и флейворы (`src/main`, `src/debug`, `src/release`, `src/<flavor>`), а также ресурсы библиотечных модулей с тем же именем.

## 3. Манифест

- `<application android:icon="@drawable/<icon>" ...>`.
- `android:roundIcon` удалить или направить на тот же `@drawable/<icon>`.
- Проверить `android:icon` / `android:roundIcon` у каждой `<activity>` с `MAIN` + `LAUNCHER` и у каждого `<activity-alias>`: атрибут на этом уровне перекрывает значение из `<application>`.
- Проверить итоговый merged manifest (`build/intermediates/merged_manifests/...`), чтобы библиотеки не подменяли иконку.

Требования:

- Проверка на свой пакет выполняется до любой обёртки (`CustomAdaptiveIconDrawable` / `AdaptiveIconDrawable` / иконка из icon pack / themed icon).
- Перекрыть все перегрузки `getIcon`, через которые в проекте идёт загрузка иконок (в референсе их три). Если архитектура не на базе Launcher3, сделать то же в месте, где результат `PackageManager` / `LauncherApps.getIcon(...)` оборачивается в маску.

### 4.2. Исключение из принудительного оборачивания не-adaptive иконок

В Launcher3-форках не-adaptive иконка может быть обёрнута в adaptive с подложкой уже после `IconProvider`, на этапе построения bitmap. В Lawnchair-форках это включается настройкой «оборачивать иконки» (`prefs_wrapAdaptive`, `IconPreferencesKt.shouldWrapAdaptive`). Без исключения собственная иконка при включённой настройке окажется уменьшенной на подложке.

Маркерный класс разместить в том же модуле, что и `BaseIconFactory` (в Lawnchair-форках это `iconloaderlib`, рядом с `app.lawnchair.icons.ExtendedBitmapDrawable`), чтобы он был виден из всех точек проверки:

```kotlin
/** Иконка с запечённой формой: не оборачивать в adaptive, не накладывать маску. */
class PreShapedIconDrawable(res: Resources, bitmap: Bitmap) : BitmapDrawable(res, bitmap)
```

Точки проверки (в Lawnchair-форках их две, обе уже исключают иконки из icon pack — добавить рядом проверку маркера):

1. `BaseIconFactory.normalizeAndWrapToAdaptiveIcon(...)` (`iconloaderlib`): построение bitmap для домашнего экрана, меню приложений, «Недавних» и т. д.

   ```java
   boolean isFromIconPack = ExtendedBitmapDrawable.isFromIconPack(icon);
   boolean isPreShaped = icon instanceof PreShapedIconDrawable;
   shrinkNonAdaptiveIcons = !isFromIconPack && !isPreShaped
           && IconPreferencesKt.shouldWrapAdaptive(mContext);
   ```

2. `Utilities.getFullDrawable(...)`: иконка при перетаскивании и анимации. Для маркерной иконки возвращать `null` так же, как для иконки из icon pack:

   ```java
   if (ExtendedBitmapDrawable.isFromIconPack(mainIcon)
           || mainIcon instanceof PreShapedIconDrawable
           || (!PreferenceManager.INSTANCE.get(context).getWrapAdaptiveIcons().get()
                   && info.itemType != LauncherSettings.Favorites.ITEM_TYPE_FOLDER))
       return null;
   ```

Требования:

- Найти в проекте все вызовы `normalizeAndWrapToAdaptiveIcon` / `wrapToAdaptiveIcon` (в т. ч. в подклассах `BaseIconFactory`, например `BubbleIconFactory`) и убедиться, что ни один из них не оборачивает маркерную иконку.
- Убедиться, что на пути от `getIcon` до точек проверки drawable не пересоздаётся (например, копированием bitmap в другой класс `BitmapDrawable`): иначе маркер теряется.
- Если модуль с `BaseIconFactory` подключён как git-сабмодуль чужого репозитория, изменение в нём требует форка сабмодуля. В этом случае остановиться и сообщить, не обходя ограничение другим способом.

## 5. Проверка

Сборка: `./gradlew assembleDebug`. Если в release включены `shrinkResources` или оптимизация ресурсов, проверить и release-сборку: пути ресурсов в APK там переименовываются, поэтому проверять через `aapt2`, а не по именам файлов.

```sh
# 1. На какой ресурс указывают icon / roundIcon
aapt2 dump xmltree --file AndroidManifest.xml app.apk | grep -iE "icon|roundIcon"

# 2. Все варианты этого ресурса по конфигурациям
aapt2 dump resources app.apk | grep -A10 "<icon>"

# 3. Корневой элемент каждого XML-варианта из вывода п. 2
aapt2 dump xmltree --file <путь из вывода п. 2> app.apk
```

Критерии приёмки:

- Каждый вариант цепочки `icon` / `roundIcon` разрешается либо в PNG, либо в XML с корнем `bitmap`. Ни одного `adaptive-icon`.
- `grep -rl "<adaptive-icon" <модуль>/src` не находит файлов, на которые ссылается иконка приложения.
- На устройстве (минимум Android 13+) сменить форму иконок в системе (для проекта-лаунчера также в его настройках) и проверить:
  - лаунчер, который рисует не-adaptive иконки без обработки (для проекта-лаунчера — он сам): домашний экран и меню приложений. Контур совпадает с силуэтом изображения, ничего не обрезано, после смены формы ничего не меняется;
  - только для проекта-лаунчера: включить в нём оборачивание не-adaptive иконок и переустановить APK (`adb install -r <apk>`), чтобы кэш иконок пересобрал запись собственного пакета. Собственная иконка по-прежнему без подложки: на домашнем экране, в меню приложений и при перетаскивании;
  - стоковые поверхности AOSP («Настройки → Приложения», share sheet, «Недавние» стокового лаунчера): иконка не обрезана. Уменьшенная иконка на подложке системной формы здесь — ожидаемое поведение (см. «Ограничения»).

## Ограничения (ожидаемое поведение, не дефект)

- Themed icons (монохромный слой, Android 13+) для такой иконки не работают: `<monochrome>` существует только внутри `<adaptive-icon>`.
- Стоковые поверхности AOSP оборачивают любую не-adaptive иконку в adaptive с однотонной подложкой и уменьшают её, после чего на подложку накладывается системная маска формы. Сама иконка не обрезается, но отображается уменьшенной внутри плашки, а не по своему силуэту. Где это происходит (по исходникам AOSP):
  - Launcher3 / Pixel Launcher и «Недавние» на его базе: `iconloaderlib`, `BaseIconFactory.wrapToAdaptiveIcon` (для любой не-adaptive иконки, масштаб `LEGACY_ICON_SCALE`);
  - «Настройки → Приложения»: SettingsLib `Utils.getBadgedIcon` → тот же `BaseIconFactory`;
  - share sheet и «Открыть с помощью»: `SimpleIconFactory.normalizeAndWrapToAdaptiveIcon`.

  Со стороны приложения это не отключается: обойти подложку может только adaptive-иконка, а она получает маску формы.
- OEM-оболочки могут добавлять собственные подложки и маски к любым иконкам независимо от их типа.
