From ce26f7c332c6e02723822fcf4292513d8ebea0ef Mon Sep 17 00:00:00 2001
From: Chip Senkbeil <chip@senkbeil.org>
Date: Sat, 30 Nov 2024 13:55:51 -0600
Subject: [PATCH] feat(img): implement skeleton of `vim.img.show()` without
 backends

Implement the skeleton of `vim.img.show()` without any backend implemented.
---
 runtime/lua/vim/img.lua          | 30 ++++++++++++++++++++++++++++++
 runtime/lua/vim/img/_backend.lua | 10 ++++++++++
 runtime/lua/vim/img/_image.lua   |  6 ++++++
 3 files changed, 46 insertions(+)
 create mode 100644 runtime/lua/vim/img/_backend.lua

diff --git a/runtime/lua/vim/img.lua b/runtime/lua/vim/img.lua
index c3961421b8..4110985f6b 100644
--- a/runtime/lua/vim/img.lua
+++ b/runtime/lua/vim/img.lua
@@ -1,4 +1,5 @@
 local img = vim._defer_require('vim.img', {
+  _backend = ..., --- @module 'vim.img._backend'
   _image = ..., --- @module 'vim.img._image'
 })
 
@@ -11,4 +12,33 @@ function img.load(opts)
   return img._image:new(opts)
 end
 
+---@class vim.img.Protocol 'iterm2'|'kitty'|'sixel'
+
+---@class vim.img.Opts: vim.img.Backend.RenderOpts
+---@field backend? vim.img.Protocol|vim.img.Backend
+
+---Displays the image within the terminal used by neovim.
+---@param image vim.img.Image
+---@param opts? vim.img.Opts
+function img.show(image, opts)
+  opts = opts or {}
+
+  local backend = opts.backend
+
+  -- For named protocols, grab the appropriate backend, failing
+  -- if there is not a default backend for the specified protocol.
+  if type(backend) == 'string' then
+    local protocol = backend
+    backend = img._backend[protocol]
+    assert(backend, 'unsupported backend: ' .. protocol)
+  end
+
+  ---@cast backend vim.img.Backend
+  backend.render(image, {
+    pos = opts.pos,
+    size = opts.size,
+    crop = opts.crop,
+  })
+end
+
 return img
diff --git a/runtime/lua/vim/img/_backend.lua b/runtime/lua/vim/img/_backend.lua
new file mode 100644
index 0000000000..1e85e54f6a
--- /dev/null
+++ b/runtime/lua/vim/img/_backend.lua
@@ -0,0 +1,10 @@
+---@class vim.img.Backend
+---@field render fun(image:vim.img.Image, opts?:vim.img.Backend.RenderOpts)
+
+---@class vim.img.Backend.RenderOpts
+---@field crop? {x:integer, y:integer, width:integer, height:integer} units are pixels
+---@field pos? {row:integer, col:integer} units are cells
+---@field size? {width:integer, height:integer} units are cells
+
+return {
+}
diff --git a/runtime/lua/vim/img/_image.lua b/runtime/lua/vim/img/_image.lua
index c7d8ba8b55..30df1b4a71 100644
--- a/runtime/lua/vim/img/_image.lua
+++ b/runtime/lua/vim/img/_image.lua
@@ -33,6 +33,12 @@ function M:size()
   return string.len(self.data or '')
 end
 
+---Displays the image within the terminal used by neovim.
+---@param opts? vim.img.Opts
+function M:show(opts)
+  vim.img.show(self, opts)
+end
+
 ---Loads data for an image from a file, replacing any existing data.
 ---If a callback provided, will load asynchronously; otherwise, is blocking.
 ---@param filename string