# バッチ設計書 73-pixels.bat

## 概要

本ドキュメントは、conpixels.exe（コンソールウィンドウのピクセル・DPI・レイアウト情報表示ツール）のラッパーバッチ `pixels.bat` のバッチ設計書である。

### 本バッチの処理概要

ビルドツリー（`%_NTTREE%`）に配置されたconpixels.exeを呼び出し、現在のコンソールウィンドウのピクセル寸法、DPI情報、フォントサイズ、スクロールバー予約領域、ビューポート文字数、モニター情報、およびウィンドウレイアウトの計算過程を詳細に表示する。コンソールウィンドウのレイアウトデバッグやDPIスケーリングの検証に使用される診断ツールである。

**業務上の目的・背景**：Windows Terminalおよびコンソールホスト（conhost.exe）の開発において、コンソールウィンドウのピクセル単位のレイアウト計算が正しく行われているかを確認する必要がある。特にマルチモニター環境やDPIスケーリング環境において、ウィンドウの寸法、クライアント領域、フォントサイズ、スクロールバーの影響、実際に表示可能な文字数の計算が重要となる。本バッチはこれらの情報を一覧表示し、さらにレイアウト計算の過程を段階的に表示することで、レイアウトに関する問題のデバッグを支援する。

**バッチの実行タイミング**：開発者がコンソールウィンドウのレイアウトやDPIスケーリングに関する問題を調査する際に手動で随時実行する。ウィンドウサイズ変更やDPI変更時の挙動確認、マルチモニター環境での表示テストに使用される。

**主要な処理内容**：
1. ビルドツリー（`%_NTTREE%`）のconpixels.exeにコマンドライン引数を透過的に渡して実行する
2. conpixels.exeがコンソールウィンドウの情報を取得して表示する：
   - ウィンドウ矩形（Window Rect）、調整済みウィンドウ矩形（Adjusted Window Rect：スケーリングあり/なし）
   - クライアント領域（Client Rect）
   - スクロールバー予約領域（スケーリングあり/なし）
   - フォントサイズ（スケーリングあり/なし）
   - ビューポート（文字数）、最大ウィンドウサイズ（文字数）、カーソル位置、バッファサイズ
   - プライマリモニター情報（名前、座標、DPI）、全モニター情報
3. レイアウト計算の過程（MATH セクション）を段階的に表示する
4. テストパターン出力（計算された文字数で数字パターンを表示）

**前後の処理との関連**：本バッチは独立した診断ツールであり、ビルドプロセス（bcz.cmd等）によってconpixels.exeがビルドされた後に使用可能となる。

**影響範囲**：読み取り専用の診断ツールであり、コンソールウィンドウやシステム設定への永続的な変更は行わない。ただし、実行開始時にSetProcessDpiAwarenessを呼び出してプロセスのDPI認識モードをPROCESS_PER_MONITOR_DPI_AWAREに設定する。

## バッチ種別

診断ツール / デバッグユーティリティ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ビルド環境 | `%_NTTREE%` 環境変数が設定されていること（razzle.cmdで設定される） |
| conpixels.exe | ビルドツリーにconpixels.exeが存在すること（ビルド済みであること） |
| Windows環境 | Windows OS上で実行する必要がある（Win32 API・DPI API使用） |
| コンソールウィンドウ | コンソール（cmd.exe）上で実行する必要がある（CONOUT$ハンドル使用） |

### 実行可否判定

`%_NTTREE%\conpixels.exe` が存在すること。コンソールウィンドウ（CONOUT$）にアクセス可能であること。存在しない場合はコマンドが見つからないエラーとなる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| %1〜%9 | 文字列 | No | なし | conpixels.exeに透過的に渡される引数（現在のconpixels.exeは引数を使用しない） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| CONOUT$ | コンソール出力ハンドル | 現在のコンソールウィンドウの出力ハンドル |
| コンソールウィンドウ | Win32ウィンドウ | GetConsoleWindow()で取得される現在のコンソールウィンドウ |
| モニター情報 | Win32 API | MonitorFromWindow/GetMonitorInfo/GetDpiForMonitorで取得 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力（コンソール） | テキスト | ウィンドウ情報、DPI情報、レイアウト計算過程、テストパターン |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | 標準出力への表示（ファイル出力なし） |
| 出力先 | コンソール（標準出力、wcout使用） |
| 文字コード | Unicode（wcout使用） |
| 区切り文字 | ラベル付きテキスト |

## 処理フロー

### 処理シーケンス

```
1. バッチ実行
   └─ %_NTTREE%\conpixels.exe にコマンドライン引数（%1〜%9）を透過的に渡す
2. conpixels.exe内部処理
   ├─ SetProcessDpiAwareness（PROCESS_PER_MONITOR_DPI_AWARE）
   ├─ CONOUT$ハンドル取得（CreateFileW）
   ├─ コンソールウィンドウハンドル取得（GetConsoleWindow）
   ├─ モニター情報取得（MonitorFromWindow）
   ├─ DPI取得（GetDpiForMonitor）
   ├─ ウィンドウ矩形取得・表示（GetWindowRect）
   ├─ 調整済みウィンドウ矩形計算・表示（UnadjustWindowRectEx / UnadjustWindowRectExForDpi）
   ├─ クライアント矩形取得・表示（GetClientRect）
   ├─ スクロールバー寸法取得・表示（GetSystemMetrics / GetSystemMetricsForDpi）
   ├─ フォントサイズ取得・表示（GetConsoleFontSize）
   ├─ スクリーンバッファ情報取得・表示（GetConsoleScreenBufferInfoEx）
   ├─ モニター情報表示（プライマリ + 全モニター列挙）
   ├─ レイアウト計算（MATH セクション）
   │   ├─ 文字数計算（クライアント幅/フォント幅）
   │   ├─ スクロールバー要否判定（バッファサイズとの比較）
   │   └─ スクロールバー考慮後の実効文字数計算
   └─ テストパターン出力（数字パターンでビューポートサイズを視覚確認）
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[conpixels.exe 呼び出し]
    B --> C[DPI認識モード設定]
    C --> D[CONOUT$ハンドル取得]
    D --> E{ハンドル有効?}
    E -->|無効| F[エラー終了]
    E -->|有効| G[ウィンドウ・モニター情報取得]
    G --> H[ウィンドウ矩形・DPI情報表示]
    H --> I[フォント・スクロールバー情報表示]
    I --> J[バッファ・ビューポート情報表示]
    J --> K[モニター情報表示]
    K --> L{フォントサイズ有効?}
    L -->|ゼロ| M[計算スキップメッセージ]
    L -->|有効| N[レイアウト計算・表示]
    N --> O[テストパターン出力]
    O --> P[バッチ終了]
    M --> P
    F --> P
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| HRESULT | ハンドルエラー | CONOUT$ハンドルの取得に失敗した場合 | コンソール環境で実行しているか確認 |
| HRESULT | モニターエラー | モニターハンドルの取得に失敗した場合 | ディスプレイ接続を確認 |
| HRESULT | DPIエラー | GetDpiForMonitorの失敗 | OS対応を確認（Windows 8.1以降が必要） |
| - | フォントサイズゼロ | フォントサイズにゼロが含まれている場合 | レイアウト計算がスキップされ、メッセージが表示される |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

エラーはRETURN_IF_*マクロ（WILライブラリ）により処理される。エラーが発生した場合は即座にHRESULTコードとともにリターンする。

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（読み取り専用） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回の実行で現在のコンソールウィンドウ情報を表示 |
| 目標処理時間 | 1秒未満 |
| メモリ使用量上限 | 最小限（Win32 API呼び出しのみ） |

## 排他制御

排他制御は不要。ウィンドウ情報の読み取りアクセスのみ。ただし、実行中にウィンドウサイズが変更された場合、取得タイミングにより不整合が生じる可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| ウィンドウ情報 | 情報取得時 | ウィンドウ矩形、クライアント矩形、DPI等 |
| フォント・スクロール情報 | 情報取得時 | フォントサイズ、スクロールバー寸法 |
| バッファ情報 | 情報取得時 | ビューポート、バッファサイズ、カーソル位置 |
| モニター情報 | 情報取得時 | モニター名、座標、DPI |
| レイアウト計算 | 計算時 | 段階的な計算過程と結果 |
| テストパターン | 計算完了後 | 数字パターン（ビューポートサイズの視覚確認） |
| エラー情報 | エラー発生時 | HRESULT、GetLastError |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 該当なし | - | - |

## 備考

- 本バッチはビルドツリー環境（`%_NTTREE%`が設定された環境）での使用を前提としている
- conpixels.exeはWindowsの内部ビルドシステム（sources/NTMAKEENVベース）でビルドされるC++コンソールアプリケーションである
- DPI認識のためにSetProcessDpiAwareness（PROCESS_PER_MONITOR_DPI_AWARE）を実行開始時に呼び出す
- GetSystemMetricsForDpiはuser32.dllから動的にロードされ、利用不可の場合はGetSystemMetricsにフォールバックする
- AdjustWindowRectExForDpi / UnadjustWindowRectExForDpi関数でDPIスケーリングを考慮したウィンドウ調整計算を行う
- ウィンドウスタイルとして WS_OVERLAPPEDWINDOW | WS_HSCROLL | WS_VSCROLL、拡張スタイルとして WS_EX_WINDOWEDGE | WS_EX_ACCEPTFILES | WS_EX_APPWINDOW を想定している
- テストパターン出力により、計算された文字数でビューポートが正しく埋まるかを視覚的に確認できる
- EnumDisplayMonitorsによりマルチモニター環境の全モニター情報を列挙する
