First checked 2026-09-29. This file was mechanically checked against
8f4638a04eon 2026-09-29 — everyfile:linecitation resolved, every backticked symbol looked up in the tree, every OPEN/planned status claim tested, and every gate or baseline number it quotes compared withtools/check_module_boundaries.shandtools/include_baseline.txt. No per-claim semantic read was done: a citation that resolves can still describe the wrong thing, so this is a floor, not a verification. Nothing was found wrong by those checks.
This document describes how ROI (Region of Interest) sizes are computed in the pixelpipe, what assumptions are made, and which modules affect the ROI.
ROI model
dt_iop_roi_tfields arex,y,width,height,scale(seesrc/develop/imageop.h).x,yare the top-left pixel of the ROI in the current buffer,width/heightare in pixels.scaleis the global factor between the full-resolution input and the current ROI.1.0means 1:1.- ROI values are integers; rounding occurs whenever a float scale is applied.
Two ROI passes
- Forward (input → output):
dt_dev_pixelpipe_get_roi_out()walks the modules in order and calls eachmodify_roi_out(). It starts from the full input(0,0,width_in,height_in,1.0)and computes the full-image processed size. It also fillspiece->buf_in/piece->buf_out(the buffer ROI published by each module). This pass is only used to computepipe->processed_width/pipe->processed_heightfor GUI sizing and export sizing. - Backward (output → input):
dt_dev_pixelpipe_get_roi_in()walks the modules in reverse and calls eachmodify_roi_in(). It starts from the requested output ROI and computes the minimal upstream ROI needed for that request. It writespiece->roi_outandpiece->roi_infor each piece; those per-piece ROIs are then used for cache hashing and bydt_dev_pixelpipe_process_rec()when actual pixels are requested.
If a module is disabled, or temporarily bypassed while editing (distortion bypass), both passes treat it as a no-op.
Where the requested ROI comes from
- Darkroom main preview (
DT_DEV_PIXELPIPE_FULL):_update_darkroom_roi()first callsdt_dev_pixelpipe_get_roi_out()to compute full-image processed size. It then computesscale = natural_scale * dev->roi.scaling, wherenatural_scalefits the full image into the viewport anddev->roi.scalingis the zoom factor. The requested ROI is the visible window:width/height = min(processed * scale, viewport)andx,yare computed from the normalized ROI centerdev->roi.x/y. Only that ROI is processed; the base buffer is cropped to it before any module runs. - Darkroom preview pipe (
DT_DEV_PIXELPIPE_PREVIEW): the same processed size andnatural_scaleare used, butdev->roi.scalingis not applied andx=y=0. The preview always renders the full image at a scale that fits the viewport. - Export and thumbnail:
dt_dev_pixelpipe_get_roi_out()computes the full-image processed size after distortions/crops/borders._get_export_size()then computes the target output size andscale = target/full. The requested ROI is{0,0,target_w,target_h,scale}. For export,finalscaleforces upstream processing at scale 1.0 and resamples at the end. For thumbnails,initialscaledoes the early resampling andfinalscaleis disabled.
Modules that change ROI
iop/basebuffer.c: first module in the pipe; slices the requested window out of the full-resolution mipmap-cache payload.modify_roi_in()always requests the whole image (x=y=0,width/height=pipe->iwidth/iheight) since the module needs the full frame available to crop from —roi_innever carries the requested offset.process()/process_cl()must read the crop offset fromroi_out(the window actually requested downstream), and usepipe->iwidth/iheight, notroi_in->width/height, for the source row stride.iop/rawprepare.c: trims sensor margins.modify_roi_out()shrinks width/height and resetsx,yto 0.modify_roi_in()expands the request to include the cropped margins.iop/demosaic.c: no scaling.modify_roi_out()snapsx,yto the mosaic origin (currently0,0).modify_roi_in()does not snap or alignx,y— any crop offset is accepted as-is;process()/process_cl()compute the correct Bayer/X-Trans phase for that exact offset on every call instead (see CLAUDE.md, "Demosaic's Bayer/X-Trans phase is computed fresh per crop, not snapped").iop/initialscale.c: early resampling for non-export pipes.modify_roi_in()requests the full input buffer (x=y=0,width/height=buf_in,scale=1.0) so the module can resample down to the requested ROI. It does not change the forward size.iop/lens.c: geometry correction padding.modify_roi_in()expands the ROI based on lensfun distortion and interpolation width;modify_roi_out()is a passthrough.iop/crop.c: rectangular crop.modify_roi_out()computes the cropped rectangle in the input.modify_roi_in()offsetsx,yby the crop origin; width/height are unchanged.iop/clipping.c: rotation/keystone + crop.modify_roi_out()computes the output bounding box and crop offsets.modify_roi_in()back-transforms the output AABB into input space and adds 1 px padding, with a fast path for pure cropping.iop/ashift.c: perspective/homography.modify_roi_out()computes the output bounds, then applies the internal crop factors.modify_roi_in()back-transforms output corners to input space and pads by interpolation width.iop/borders.c: frame/border.modify_roi_out()expands width/height to include borders.modify_roi_in()subtracts borders so only image pixels are requested from upstream.iop/finalscale.c: export and GUI upscaling.modify_roi_in()mapsroi_outback to scale 1.0 when exporting or whenroi_out.scale > 1, so upstream modules stay at 1:1 and finalscale does the resampling. It does not change the forward size.
Assumptions and pitfalls
- Cache hashes include the per-piece ROI values (
piece->roi_in/piece->roi_out) (as well as descriptors likepiece->dsc_in/piece->dsc_out), so any rounding mismatch between forward/backward ROI passes causes cache misses or incorrect reuse. Modules generally clamp and add interpolation padding to mitigate this. - ROI is integer-based but
scaleis float. All resampling is handled byinitialscaleandfinalscale; the base buffer path only supportsscale == 1.0for the raw/full input copy. - During GUI editing, distortion modules can be bypassed to give an undistorted view for the active module. This affects ROI planning and hashes by design.
piece->iwidth/piece->iheight(the full native input size) are a coarser, separate measurement fromroi_*/buf_*: they are copied frompipe->iwidth/iheightonce, indt_dev_pixelpipe_create_nodes(), not refreshed on every ROI pass. Darkroom pipes calldt_dev_pixelpipe_set_input()(which setspipe->iwidth/iheight) before creating their nodes, so the copy is correct there. The export pipe (imageio/imageio_core.c) creates its nodes first and only callsset_input()afterwards, once the real mipmap buffer size is known — so everypiece->iwidth/iheightwas permanently baked in at 0 on export, while darkroom was unaffected. Any module sizing itself frompiece->iwidth/iheightdirectly (instead ofroi_out->scaleand apiece->buf_indimension) silently lost that sizing on export only. Any per-piece field seeded frompipe->*at node-creation time is exposed to the same ordering hazard if a caller can set thatpipe->*field after creating nodes.