From 2cb27de2878e86100694866becd51c1bbde6c410 Mon Sep 17 00:00:00 2001 From: Hirohito Higashi Date: Sun, 4 Oct 2026 04:39:43 +0900 Subject: [PATCH] Update popup.{txt,jax} --- doc/popup.jax | 121 +++++++++++++++++++++++++----------------------- en/popup.txt | 124 ++++++++++++++++++++++++++------------------------ 2 files changed, 127 insertions(+), 118 deletions(-) diff --git a/doc/popup.jax b/doc/popup.jax index e9b8a1385..59d7b1153 100644 --- a/doc/popup.jax +++ b/doc/popup.jax @@ -1,4 +1,4 @@ -*popup.txt* For Vim バージョン 9.2. Last change: 2026 Jul 29 +*popup.txt* For Vim バージョン 9.2. Last change: 2026 Sep 30 VIM リファレンスマニュアル by Bram Moolenaar @@ -435,6 +435,11 @@ popup_getoptions({id}) *popup_getoptions()* "textprop", "textpropid" および "textpropwin" は、"textprop" が設定されている場合にのみ与えられる。 + "image" エントリは、|image_info()| が返すものと同じフィールド + を持つ辞書である。Note 画像がポップアップによって直接作成され + た場合、"id" フィールドは含まれないことに注意。|popup-image|を + 参照。 + ポップアップウィンドウ {id} が見つからない場合は空の辞書が返さ れる。 @@ -620,6 +625,7 @@ popup_setoptions({id}, {options}) *popup_setoptions()* firstline flip highlight + image mapping mask moved @@ -808,18 +814,9 @@ popup_create() に渡す。 れ、部分的に透明になる。'termguicolors' を設定する必要 がある。 |popup-opacity| も参照。 - image ポップアップ内にレンダリングする生の RGB または RGBA - ピクセルバッファを記述する辞書。設定すると、ポップアッ - プは画像のピクセル寸法からセルボックスのサイズを自動的 - に調整するため、"minwidth" / "minheight" / "maxwidth" - / "maxheight" を手動で設定する必要はない。キーは以下: - data バイトの |Blob|。長さは幅 x 高さ x 3 (RGB) - または幅 x 高さ x 4 (RGBA) と等しくなけれ - ばならない。 - width ピクセル単位の画像の幅。 - height ピクセル単位の画像の高さ。 - 以前に設定した画像を削除するには、空の辞書を使用する。 - |popup-image| を参照。 + image 画像を表示するための辞書である。必須フィールドについて + は |image_add()| を参照。あるいは "id" フィールドのみ + を指定することも可能である。|popup-image| を参照。 padding ポップアップの上/右/下/左のパディングを定義する数値の リスト(CSSと同様)。空のリストは、すべて 1 のパディング を使用する。パディングは、テキストをボーダーの内側で囲 @@ -1168,42 +1165,59 @@ Note "x" はポップアップを閉じる通常の方法である。Escを使 4隅を透明にするには: [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]] -☆ポップアップの画像 *popup-image* - -ポップアップウィンドウは、|popup_create()| または |popup_setoptions()| に -"image" 辞書を渡すことで、テキストの代わり (またはテキストの上) に画像を表示で -きる。呼び出し元は既にデコードされた生のピクセルバッファを提供し、Vim は実行時 -に利用可能なバックエンドを通してそれを出力する。 - - sixel sixel 対応端末における DEC sixel DCS シーケンス。|+image_sixel|。 - 自動的に検出される。また、sixel に起因する端末のスクロールを防ぐた - め、バッファは画面端の 1 セル上で切り詰められる。 - kitty kitty グラフィックスプロトコル APC シーケンスは、対応する端末 - (kitty、ghostty、WezTerm、Konsole など) で使用できる。 - |+image_kitty|。 - 端末へのアクティブな問い合わせによって検出される。 - GDI MS-Windows GUI 上の GUI キャンバスに StretchDIBits を配置する。 - |+image_gdi|。 - Cairo GTK GUI 上の cairo_image_surface_t に合成する (GTK 2 および GTK 3 - に対応)。 |+image_cairo|。 - GDK GPU に画像をアップロードしてレンダリングを高速化する GdkTexture - を使用する (GTK 4 のみ有効)。|+image_gdk| - -Vim 自体は libpng、libjpeg、libwebp、または画像デコーダーにリンクしない。 -フォーマットのデコードは呼び出し元に任されており、呼び出し元はファイルを任意の -外部ツール (GraphicsMagick、ImageMagick、ffmpeg、カスタムコンバーターなど) に -パイプで渡し、結果として得られたバイト列を |Blob| で渡すことができる。 - -"image" 辞書は以下を受け入れる: - data バイト単位の |Blob|。長さは、RGB の場合は幅 x 高さ x 3、 - RGBA の場合は幅 x 高さ x 4 以上である必要がある。RGBA バッファ - は、ポップアップの背景画像にアルファ合成される。 - width ピクセル単位の画像の幅。 - height ピクセル単位の画像の高さ。 - -ポップアップのセルボックスはピクセル寸法と端末 / GUI セルのメトリクスから生成 -されるため、呼び出し元は通常 "minwidth" / "minheight" / "maxwidth" / -"maxheight" を設定する必要はない。 +☆ポップアップの画像 *image* *popup-image* + +Vim は、端末と GUI の両方で画像を表示する機能を備えている。この機能を使用する +には、pixman ライブラリとのリンクが必要である。同ライブラリは、Unix 系 OS では +パッケージマネージャーから、MS-Windows では vcpkg からインストールできる。画像 +表示がサポートされているかどうかは、|+image| および |+image_popup| を確認する +ことで確かめられる。 + +ポップアップウィンドウには、画像を表示させることもできる。そのためには、辞書を +含む "image" という名前のフィールドを |popup_create()| または +|popup_setoptions()| に渡す。この辞書には、|image_add()| と同じフィールドを含 +めるか、あるいは "id" フィールドを使用して ID 経由で画像を参照させることができ +る。"id" フィールドが優先的に扱われる。|image_add()|、|image_discard()|、 +|image_info()| を参照。 + +ポップアップウィンドウによって画像が直接作成される場合 (例えば、"id" が使用さ +れていない場合)、その画像は内部的なものとみなされ、他の場所から参照することは +できない。 + +ポップアップウィンドウに以前設定した画像を解除するには、空の辞書を渡す: > + call popup_setoptions(winid, #{image: {}}) +< + *image-backends* +すべてのプラットフォームでサポートされている端末の画像プロトコルは 2 種類ある。 +使用するプロトコルは、'imageprotocol' オプションで選択する。 + + sixel sixel プロトコルを使用して画像を表示する。 + kitty kitty グラフィックスプロトコルを使用する。sixel よりもはるかに高い + パフォーマンスを発揮するため、使用可能な場合は、端末でこのプロトコ + ルを使用することが推奨される。 + +GUI を使用する場合、Vim の GTK4、GTK3、および Win32 版がサポートされている。 + +現在使用されている画像バックエンドを確認するには、|v:imagebackend| 変数を使用 +する。 + + *image-options* +RGBA バッファを渡す際、Vim はそれがエンディアンに依存せず、かつ non alpha +pre-multiplied 形式であることを想定している。RGB 画像の場合、各ピクセルは正確 +に 3 バイトである必要があり、パディングバイトは Vim ではサポートされていない。 + +画像を含むポップアップのサイズは、画像の寸法および端末や GUI のセルサイズに基 +づいて自動的に計算される。ただし、"minwidth"、"minheight"、"maxwidth"、 +"maxheight" の各フィールドを使用し、この設定を上書きすることも可能である。 + +画像は縮小されない。ポップアップウィンドウがその中の画像よりも小さい場合、画像 +は切り抜かれる。 + + *image-animation* +|popup_setoptions()| を使用すると、実行時にポップアップウィンドウの画像を変更 +できる。新しい画像が既存の画像と同じ形式、幅、高さである場合、既存の画像がその +場で書き換えられる。これは、|timer| を使用したフレーム単位のアニメーションを行 +うのに十分なパフォーマンスを備えている。 エディタの実際の背景にきれいにブレンドする必要がある RGBA バッファの場合、スク リプトは |getbgcolor()| を呼び出して現在の背景色を [r、g、b] として取得し、そ @@ -1230,15 +1244,6 @@ Vim 自体は libpng、libjpeg、libwebp、または画像デコーダーにリ \ line: 1, col: 1, border: [], padding: [0, 0, 0, 0], \ }) -画像は、|popup_setoptions()| を使用して実行時に置き換えることができる。新しい -バッファの幅と高さが現在のバッファと同じ場合、ピクセルがその場で交換される。こ -れは、|timer| からフレームごとのアニメーションを駆動するのに十分な速さである。 -|popup_getoptions()| は同じ辞書を返す。"data" エントリは、ポップアップの内部 -バッファとは独立した新しい blob のコピーである。 - -以前に設定した画像を削除するには、空の辞書を渡す: > - call popup_setoptions(winid, #{image: {}}) - ============================================================================== 4. 例 *popup-examples* diff --git a/en/popup.txt b/en/popup.txt index d002df11d..a170d8ce1 100644 --- a/en/popup.txt +++ b/en/popup.txt @@ -1,4 +1,4 @@ -*popup.txt* For Vim version 9.2. Last change: 2026 Jul 29 +*popup.txt* For Vim version 9.2. Last change: 2026 Sep 30 VIM REFERENCE MANUAL by Bram Moolenaar @@ -427,6 +427,11 @@ popup_getoptions({id}) *popup_getoptions()* "textprop", "textpropid" and "textpropwin" are only present when "textprop" was set. + The "image" entry is a dictionary with the same fields as + returned by |image_info()|. Note that if the image is created + directly by the popup, the "id" field will not be present, see + |popup-image|. + If popup window {id} is not found an empty Dict is returned. Can also be used as a |method|: > @@ -609,6 +614,7 @@ popup_setoptions({id}, {options}) *popup_setoptions()* firstline flip highlight + image mapping mask moved @@ -801,18 +807,9 @@ The second argument of |popup_create()| is a dictionary with options: underlying text, making it partially transparent. Requires 'termguicolors' to be set. Also see |popup-opacity|. - image Dictionary describing a raw RGB or RGBA pixel buffer - to render inside the popup. When set the popup - auto-sizes its cell box from the image's pixel - dimensions, so "minwidth" / "minheight" / "maxwidth" / - "maxheight" do not need to be set by hand. Keys: - data |Blob| of bytes; length must equal - width*height*3 (RGB) or width*height*4 - (RGBA). - width image width in pixels. - height image height in pixels. - Use an empty dictionary to remove a previously set - image. See |popup-image|. + image Dictionary for displaying an image. See |image_add()| + for required fields, or you can provide the "id" field + only, see |popup-image|. padding List with numbers, defining the padding above/right/below/left of the popup (similar to CSS). An empty list uses a padding of 1 all around. The @@ -1170,44 +1167,60 @@ For example, to make the last 10 columns of the last line transparent: To make the four corners transparent: [[1, 1, 1, 1], [-1, -1, 1, 1], [1, 1, -1, -1], [-1, -1, -1, -1]] -POPUP IMAGE *popup-image* - -A popup window can render an image instead of (or on top of) text by passing -an "image" dictionary to |popup_create()| or |popup_setoptions()|. The caller -supplies an already-decoded raw pixel buffer and Vim emits it through -whichever backend is available at runtime: - - sixel DEC sixel DCS sequence on a sixel-capable terminal. - |+image_sixel|. Detected automatically; the buffer is also - cropped one cell above the screen edge to avoid sixel-induced - terminal scrolling. - kitty kitty graphics protocol APC sequence on terminals that support it - (kitty, ghostty, WezTerm, Konsole, ...). |+image_kitty|. - Detected by actively querying the terminal. - GDI StretchDIBits onto the GUI canvas on the MS-Windows GUI. - |+image_gdi|. - Cairo composite onto a cairo_image_surface_t on the GTK GUI - (covers GTK 2 and GTK 3). |+image_cairo|. - GDK Use GdkTexture, which uploads the image onto the GPU for faster - rendering (only for GTK 4). |+image_gdk| - -Vim itself does NOT link against libpng, libjpeg, libwebp or any image -decoder. Format decoding is left to the caller, who can pipe the file through -any external tool (GraphicsMagick, ImageMagick, ffmpeg, a custom converter, -...) and pass the resulting bytes via a |Blob|. - -The "image" dictionary accepts: - data |Blob| of bytes. Length must equal width*height*3 for RGB, - or width*height*4 for RGBA. RGBA buffers are alpha-composited - over the popup's background. - width image width in pixels. - height image height in pixels. - -The popup's cell box is derived from the pixel dimensions and the terminal / -GUI cell metrics, so the caller does not normally have to set "minwidth" / -"minheight" / "maxwidth" / "maxheight". - -For RGBA buffers that need to blend cleanly into the editor's actual backdrop +POPUP IMAGE *image* *popup-image* + +Vim is capable of displaying graphical images, in both the terminal and GUI. +To do this, it must link with the pixman library, which you may install via +your package manager on Unix, or via vcpkg on MS-Windows. You may see if +images are supported by checking |+image| and |+image_popup|. + +A popup window may additionally render an image. To do this, pass a field +named "image" containing a dictionary to |popup_create()| or +|popup_setoptions()|. The dictionary may either have the same fields as in +|image_add()|, or it may reference an image via its ID using the "id" field. +The "id" field is prioritized first, see |image_add()|, |image_discard()|, and +|image_info()|. + +When an image is directly created by a popup window (e.g. "id" is not used), +then it is considered internal and can not be referenced anywhere else. + +To unset a previously set image from a popup window pass an empty dictionary: > + call popup_setoptions(winid, #{image: {}}) +< + *image-backends* +There are two terminal image protocols supported on all platforms. The +protocol to use is chosen using the 'imageprotocol' option: + + sixel Uses the sixel protocol to display images. + kitty Uses the kitty graphics protocol. This is the recommended + protocol to use in the terminal if it is available, as it is much + more performant than sixel. + +When using the GUI, the GTK4, GTK3, and Win32 versions of Vim are supported. + +To see what image backend is currently being used, use the |v:imagebackend| +variable. + + *image-options* +When passing an RGBA buffer, Vim expects it to be endian independent and non +alpha pre-multiplied. For RGB images, each pixel should be exactly 3 bytes, +a padding byte is not supported by Vim. + +The dimensions of a popup containing an image are automatically calculated +based on the image dimensions and terminal/GUI cell size. However, you may +override it using the "minwidth", "minheight", "maxwidth", and "maxheight" +fields. + +Images are not scaled, if a popup window is smaller than the image it +contains, then the image will be cropped instead. + + *image-animation* +The image of a popup window can be changed at runtime using +|popup_setoptions()|. When the new image has the same format, width, and +height as the existing image, the existing image will be modified in place. +This is performant enough for frame-by-frame animation, using a |timer|. + +For RGBA buffers that need to blend cleanly into the editor's actual backdrop, the script can call |getbgcolor()| to obtain the current background colour as [r, g, b] and pre-composite anti-aliased edges against it. @@ -1232,15 +1245,6 @@ raw RGB bytes: > \ line: 1, col: 1, border: [], padding: [0, 0, 0, 0], \ }) -The image can be replaced at runtime via |popup_setoptions()|. When the new -buffer has the same width and height as the current one the pixels are swapped -in place, which is fast enough to drive frame-by-frame animation from a -|timer|. |popup_getoptions()| returns the same dictionary back; the "data" -entry is a fresh blob copy independent of the popup's internal buffer. - -To remove a previously set image pass an empty dictionary: > - call popup_setoptions(winid, #{image: {}}) - ============================================================================== 4. Examples *popup-examples*