Set or change decoration provider for a namespace

This is a very general purpose interface for having lua callbacks being triggered during the redraw code.

The expected usage is to set extmarks for the currently redrawn buffer. nvim_buf_set_extmark() can be called to add marks on a per-window or per-lines basis. Use the ephemeral key to only use the mark for the current screen redraw (the callback will be called again for the next redraw ).

Note: this function should not be called often. Rather, the callbacks themselves can be used to throttle unneeded callbacks. the on_start callback can return false to disable the provider until the next redraw. Similarly, return false in on_win will skip the on_lines calls for that window (but any extmarks set in on_win will still be used). A plugin managing multiple sources of decoration should ideally only set one provider, and merge the sources internally. You can use multiple ns_id for the extmarks set/modified inside the callback anyway.

Note: doing anything other than setting extmarks is considered experimental. Doing things like changing options are not expliticly forbidden, but is likely to have unexpected consequences (such as 100% CPU consumption). doing vim.rpcnotify should be OK, but vim.rpcrequest is quite dubious for the moment.

Attributes: Lua vim.api only

Parameters:

• {ns_id} Namespace id from nvim_create_namespace()
• {opts} Table of callbacks: - on_start: called first on each screen redraw ["start", tick] - on_buf: called for each buffer being redrawn (before window callbacks) ["buf", bufnr, tick] - on_win: called when starting to redraw a specific window. ["win", winid, bufnr, topline, botline_guess] - on_line: called for each buffer line being redrawn. (The interaction with fold lines is subject to change) ["win", winid, bufnr, row] - on_end: called at the end of a redraw cycle ["end", tick]