Synopsis

struct DecorImage * DCreateDecorImageContainerMatchingScreen(
   struct DecorImage *in, BOOL truecolor, struct Screen *scr)

Function

Create an image copy prepared for a target screen.

Inputs

in - Source DecorImage with a valid filename, dimensions and nonzero
    subimage grid consistent with those dimensions; normally returned
    by DGetImageFromFile(). NULL requests an empty unusable container.
truecolor - TRUE to use copied ARGB data; FALSE to try palette-matched
    picture loading for the target screen.
scr - Live, non-NULL Screen with a valid RastPort.BitMap. Keep the
    screen open until the returned image has been disposed.

Result

Owned DecorImage on normal completion. Check its ok flag before use;
a returned container can be unusable. Allocation failures are not
reliably converted to a NULL result.

Notes

Dimensions and grid counts are copied. Source pixels, when present,
are copied into a separate allocation. The source remains caller-owned
and must stay stable until return; it is not retained afterward.

The palette path first loads filename with _LUT appended, then tries
the original file remapped to scr. The true-color path does not reopen
the file, but still requires a valid source filename. Relative names
use the process's current directory at conversion time.

For copied pixels, fully opaque subimages are recorded in a decision
table and may receive an auxiliary screen-compatible bitmap. No grid,
buffer-size or arithmetic validation is performed. A zero grid count
can cause division by zero.

Dispose the result with DDisposeImageContainer() before closing scr.
Call from a DOS process with decorator.library open. Conversion and
any picture loading are synchronous and have no caller timeout.

Bugs

Several allocations and rendering resources are used without checks.
Memory exhaustion can cause invalid memory access. When palette loading
succeeds and copied source pixels are also present, the datatype-object
pointer is cleared without disposal, leaking its owned resources.

See also

DGetImageFromFile() DDisposeImageContainer()

Synopsis

void DDisposeImageContainer(
   struct DecorImage *di)

Function

Release an owned ARGB image container and its associated resources.

Inputs

di - Owned DecorImage, or NULL for no operation.

Result

None.

Notes

Releases the pixel buffer, filename, subimage decision table and
auxiliary bitmap. If a datatype object is present, it is disposed;
its bitmap and mask are not separately freed. An unrelated bitmap
assigned only to the bitmap field is not independently released.

Stop all rendering and other access before disposal. The call does
not detach element descriptors, release references held elsewhere or
detect shared ownership. Each owned allocation must have one owner.
Do not dispose images borrowed from a theme or screen instance.

Call once in task context with decorator.library open. Do not reuse
the container or any pointers into its owned resources after return.

See also

DNewDecorImageContainer() DGetImageFromFile() DScaleDecorImage()

Synopsis

void DDisposeLUT8ImageContainer(
   struct DecorImageLUT8 *di)

Function

Release an owned eight-bit image container and its pixel buffer.

Inputs

di - Owned DecorImageLUT8, or NULL for no operation.

Result

None.

Notes

Stop all access before calling. The buffer and container are freed;
no reference counting, synchronization or shared-buffer detection is
performed. Call once in task context with decorator.library open.

See also

DNewLUT8ImageContainer()

Synopsis

void DDrawPartImageToRP(
   struct RastPort *rp, struct DecorImage *di, UWORD x, UWORD y, UWORD sx, UWORD sy, UWORD sw, UWORD sh)

Function

Copy a rectangular part of an image to a RastPort.

Inputs

rp - Non-NULL destination RastPort with a writable bitmap.
di - Non-NULL source image. An image with ok == FALSE is ignored.
x, y - Destination top-left coordinates, in pixels.
sx, sy - Source top-left coordinates, in pixels.
sw, sh - Positive rectangle dimensions, within the source image.

Notes

Uses di->bitmap when present; otherwise reads packed ARGB bytes
from di->data, with a row stride of di->w * 4 bytes. The stride
must fit the pixel-array API's UWORD argument.

This is a copy, not alpha compositing. The mask and bitmap2 fields
are ignored. The source is neither modified nor consumed. Keep its
selected storage valid and exclude concurrent modification during use.
Source bounds are not checked.

See also

DDrawPartToImage() DDrawStatefulGadgetImageToRP() `WritePixelArray()`_

Synopsis

void DDrawPartToImage(
   struct DecorImage *src, struct DecorImage *dest, UWORD sx, UWORD sy, UWORD sw, UWORD sh, UWORD dx, UWORD dy)

Function

Copy a rectangle of ARGB pixels between image buffers.

Inputs

src - Non-NULL image with readable packed ARGB pixel storage.
dest - Non-NULL image with writable packed ARGB pixel storage.
sx, sy - Source top-left coordinates, in pixels.
sw, sh - Positive rectangle dimensions, within both image buffers.
dx, dy - Destination top-left coordinates, in pixels.

Notes

All four bytes of each pixel are copied unchanged. Source and
destination rows use their respective image widths as pixel strides.
The buffers must not overlap. Bounds and ok flags are not checked.
Neither image is consumed; metadata and bitmap caches are unchanged.
Exclude concurrent access to the destination while copying.

See also

DDrawPartImageToRP() DWriteAlphaPixelArray()

Synopsis

void DDrawScaledStatefulGadgetImageToRP(
   struct RastPort *rp, struct DecorImage *di, ULONG state, UWORD xp, UWORD yp, WORD scaledwidth, WORD scaledheight)

Function

Draw a gadget-state image cell at the requested size.

Inputs

rp - Non-NULL destination RastPort with a writable bitmap.
di - Non-NULL image with nonzero subimagescols and subimagesrows.
    Each grid cell must have positive dimensions.
state - IDS_SELECTED selects column 1; IDS_INACTIVENORMAL selects
    column 2. IDS_NORMAL and all other values select column 0.
xp, yp - Destination top-left coordinates, in pixels.
scaledwidth, scaledheight - Positive destination dimensions, in pixels.
    Use -1 for the natural cell size on either axis. Zero is invalid.

Notes

Uses row 0. Natural cell dimensions are the image dimensions divided
by the grid dimensions, rounded down. Any negative size selects the
natural size on that axis. Does nothing if ok is FALSE or the selected
column is outside the grid.

A size change samples packed ARGB data without interpolation, then
alpha-composites the result. This requires di->data even if bitmap
caches exist. Keep dimensions and products within DScaleBuffer()'s
limits and all ARGB row strides within the pixel-array API's UWORD
range. At natural size, drawing follows DDrawStatefulGadgetImageToRP().

The image is borrowed. Keep its storage valid and exclude concurrent
modification during use.

Bugs

Scaling allocation failures are not checked and can cause invalid
memory access. The function provides no error result.

See also

DDrawStatefulGadgetImageToRP() DScaleBuffer()

Synopsis

void DDrawStatefulGadgetImageToRP(
   struct RastPort *rp, struct DecorImage *di, ULONG state, UWORD xp, UWORD yp)

Function

Draw the first-row image cell selected by a gadget state.

Inputs

rp - Non-NULL destination RastPort with a writable bitmap.
di - Non-NULL image with nonzero subimagescols and subimagesrows.
    Each grid cell must have positive dimensions.
state - IDS_SELECTED selects column 1; IDS_INACTIVENORMAL selects
    column 2. IDS_NORMAL and all other values select column 0.
xp, yp - Destination top-left coordinates, in pixels.

Notes

Draws at the cell's natural size: image width divided by column
count and image height divided by row count, rounded down. Does
nothing if ok is FALSE or the selected column is outside the grid.

Cells without a bitmap-cache marker are alpha-composited from packed
ARGB data. Marked cells use the available bitmap caches; bitmap uses
its mask when present, and bitmap2 is copied without a mask. Keep
the cache markers consistent with the available storage. ARGB row
strides must fit the pixel-array API's UWORD argument.

The image is borrowed. Keep its storage valid and exclude concurrent
modification during use.

See also

DDrawScaledStatefulGadgetImageToRP() DCreateDecorImageContainerMatchingScreen()

Synopsis

void DFillMemoryBufferRGBGradient(
   UBYTE *buf, LONG pen, LONG xt, LONG yt, LONG xb, LONG yb, LONG xp, LONG yp, LONG w, LONG h, ULONG start_rgb, ULONG end_rgb, LONG angle)

Function

Write a packed RGB gradient into a caller-owned buffer.

Inputs

buf - Writable buffer of at least w * h * 3 bytes, or NULL to do
    nothing. Output starts at buf with no row padding.
pen - Ignored.
xt, yt, xb, yb - Inclusive gradient bounds, with xb >= xt and yb >= yt.
xp, yp - Requested starting sample coordinates. Only yp affects output.
w, h - Positive output dimensions, in pixels.
start_rgb, end_rgb - Numeric 0x00RRGGBB colors; high bytes are ignored.
angle - Gradient angle in degrees, normalized modulo 360. Avoid the
    minimum LONG value, whose negation cannot be represented.

Notes

Writes three bytes per pixel in red, green, blue order. At 0 degrees
color varies down the rows; at 90 degrees it varies across columns.
Samples use integer division; endpoint colors are not guaranteed to
appear exactly at the last output pixel.

Keep dimensions, coordinate differences, allocation size and gradient
intermediate products within signed arithmetic limits. Samples outside
the gradient are not clamped; out-of-range components narrow to bytes.
The buffer remains owned by the caller and must not be accessed
concurrently while it is being filled.

Bugs

The horizontal start offset xp - xt is omitted from the accumulator.
Changing xp therefore does not shift the sampled gradient. Bounds and
arithmetic overflow are not checked.

See also

DFillPixelArrayGradient() DHorizRepeatBuffer()

Synopsis

void DFillPixelArrayGradient(
   LONG pen, BOOL tc, struct RastPort *rp, struct GradientSpec *spec)

Function

Fill a RastPort rectangle from a generated RGB gradient column.

Inputs

pen - Solid-fill pen when tc is FALSE; -1 selects pen 2.
tc - TRUE for RGB output; FALSE for a solid pen fill.
rp - Non-NULL destination RastPort with a writable bitmap.
spec - Non-NULL GradientSpec. gs_xt, gs_yt, gs_xb and gs_yb are
    inclusive gradient bounds. gs_xp and gs_yp locate the destination;
    gs_w and gs_h give its size. Nonpositive sizes do nothing.
    gs_StartRGB and gs_EndRGB are numeric 0x00RRGGBB colors.
    gs_Angle is in degrees; gs_dy selects the first generated sample.
    gs_dx is ignored.

Notes

Generates gs_yb RGB samples, then repeats each selected sample across
one output row. This produces a column-based fill even for angles
that would imply horizontal color variation. Require gs_yb > 0,
0 <= gs_dy and gs_dy + gs_h <= gs_yb. Bounds and arithmetic must
satisfy DFillMemoryBufferRGBGradient(); RGB output dimensions must
also satisfy DHorizRepeatBuffer().

The specification is borrowed. The solid-fill path changes the
foreground pen and uses the existing drawing mode and area pattern.

Bugs

Column length uses gs_yb, not the gradient height. Sample bounds and
allocation sizes are not checked. If column allocation fails, RGB
output may read through NULL; no failure status is returned.
Horizontal gradient offsets are not implemented.

See also

DFillMemoryBufferRGBGradient() DHorizRepeatBuffer()

Synopsis

struct DecorImage * DGetImageFromFile(
   STRPTR path, STRPTR name, ULONG expectedsubimagescols, ULONG expectedsubimagesrows)

Function

Load a picture file into an owned ARGB image container.

Inputs

path - Non-NULL, NUL-terminated directory path.
name - Non-NULL, NUL-terminated name appended with DOS AddPart().
expectedsubimagescols, expectedsubimagesrows - Positive grid counts
    stored in the result. Supply counts consistent with the image
    dimensions; this function does not validate the grid.

Result

Owned DecorImage, or NULL when the file cannot be opened as a picture,
no bitmap header is available, or checked image allocation fails.
A non-NULL result does not prove that pixel decoding succeeded.

Notes

The image contains tightly packed ARGB bytes. For indexed pictures
using a transparent-color index, matching source pixels receive zero
alpha and other pixels receive full alpha. The temporary datatype
object is disposed before return.

The combined filename is copied into the result without resolving it
to an absolute path. Input strings need remain valid only until return.
Use a stable absolute path if the image will later be screen-matched.
No extension is added and no alternate filename is tried here.

Release the result with DDisposeImageContainer(). Call from a DOS
process with decorator.library open. File access and picture decoding
are synchronous, with no caller timeout.

Bugs

Path and filename allocations are unchecked. Allocation failure can
cause invalid memory access. The pixel-read method's result is ignored
and ok is set TRUE even if that method fails.

See also

DDisposeImageContainer() DCreateDecorImageContainerMatchingScreen()

Synopsis

struct DecorImage * DGetImageFromRP(
   struct RastPort *rp, UWORD x, UWORD y, UWORD w, UWORD h)

Function

Read a RastPort rectangle into a newly allocated ARGB image.

Inputs

rp - Non-NULL source RastPort with a readable bitmap.
x, y - Source top-left coordinates, in pixels.
w, h - Positive rectangle dimensions, within the source. The byte
    stride w * 4 must fit a UWORD, so w must not exceed 16383.
    Allocation size must satisfy DNewDecorImageContainer()'s limits.

Result

New image owned by the caller, or NULL if container allocation fails.
Release it with DDisposeImageContainer(), or transfer it to
DPutImageToRP(). A non-NULL result does not confirm a complete read.

Notes

The buffer contains packed ARGB pixels with a w * 4 byte row stride.
The container retains its initial 1-by-1 subimage grid, NULL filename
and FALSE ok flag. Consumers that require ok == TRUE will skip it.
The source RastPort is borrowed and is not modified by this function.

Bugs

The pixel-read result is ignored. An incomplete or failed read is not
reported, and the returned image is not marked valid.

See also

DPutImageToRP() DNewDecorImageContainer() DDisposeImageContainer()

Synopsis

void DHorizRepeatBuffer(
   UBYTE *buf, LONG offy, LONG pen, BOOL tc, struct RastPort *rp, LONG x, LONG y, LONG w, LONG h)

Function

Repeat each RGB sample across a destination row.

Inputs

buf - Readable packed RGB column, three bytes per sample. Required
    only when tc is TRUE; must contain at least offy + h samples.
offy - Nonnegative first sample index. There is no vertical wrapping.
pen - Foreground pen for tc == FALSE; -1 selects pen 2.
tc - TRUE for RGB output; FALSE for a solid pen fill.
rp - Non-NULL destination RastPort with a writable bitmap.
x, y - Destination top-left coordinates, in pixels.
w, h - Destination dimensions. Nonpositive values do nothing.

Notes

RGB output expands sample offy + row across all w pixels of that row.
Keep w * 3 within UWORD range, h and destination coordinates within
the pixel-array interface range, and w * h * 3 within allocation and
address arithmetic limits. Allocation failure leaves the destination
unchanged and is not reported.

The pen path ignores buf and offy, changes the foreground pen, and
uses the RastPort's existing drawing mode and area pattern. RastPort
state is not restored. Input storage is borrowed for the call.

See also

DFillPixelArrayGradient() `WritePixelArray()`_

Synopsis

void DHorizVertRepeatDecorImage(
   struct DecorImage *di, ULONG color, UWORD offx, UWORD offy, struct RastPort *rp, UWORD x, UWORD y, WORD w, WORD h)

Function

Fill a rectangle by repeating an image, or with a fallback color.

Inputs

di - Non-NULL image. For image drawing, provide a nonempty image
    with a 1-by-1 subimage grid and consistent pixel or bitmap storage.
color - Fallback color, as a numeric 0xAARRGGBB value.
offx, offy - Initial source offsets, reduced modulo the image size.
rp - Non-NULL destination RastPort with a writable bitmap.
x, y - Destination top-left coordinates, in pixels.
w, h - Destination dimensions, in pixels. Nonpositive values do nothing.

Notes

If ok is FALSE, fills the rectangle with color using FillPixelArray().
Otherwise repeats the image in both directions, cropping tiles at the
rectangle edges. Tiles are not scaled. Transparency and bitmap-cache
selection follow DDrawStatefulGadgetImageToRP(). ARGB row strides must
fit the pixel-array API's UWORD argument.

The image is borrowed. Keep its storage valid and exclude concurrent
modification during use. Image dimensions and grid values are not
validated.

See also

DDrawStatefulGadgetImageToRP() `FillPixelArray()`_

Synopsis

struct DecorImage * DNewDecorImageContainer(
   UWORD w, UWORD h)

Function

Allocate an empty ARGB image container and pixel buffer.

Inputs

w, h - Positive pixel dimensions. Their product and the four-byte
    pixel allocation must fit the target's arithmetic and allocation
    limits; no size validation is performed.

Result

Owned DecorImage, or NULL if the container or pixel allocation fails.

Notes

The buffer is cleared and tightly packed, with four bytes per pixel
in alpha, red, green, blue order in memory. The subimage grid is 1 by 1.
The ok flag remains FALSE; initialize the pixels and set it TRUE before
passing the image to rendering operations that test that flag.

No filename, datatype object, screen bitmap or subimage decision table
is created. This container alone is not a valid source for
DCreateDecorImageContainerMatchingScreen(), which expects a filename.

Release the result with DDisposeImageContainer(). Call in task context
with decorator.library open. Zero dimensions have no defined useful
image result and must not be used.

See also

DDisposeImageContainer() DScaleDecorImage() DGetImageFromFile()

Synopsis

struct DecorImageLUT8 * DNewLUT8ImageContainer(
   UWORD w, UWORD h)

Function

Allocate an empty eight-bit image container and pixel buffer.

Inputs

w, h - Positive pixel dimensions. The product must fit the target's
    signed multiplication and allocation limits; it is not checked.

Result

Owned DecorImageLUT8, or NULL if either allocation fails.

Notes

The tightly packed w*h byte buffer is cleared. No palette is allocated
or attached. Pixel interpretation belongs to the consuming operation;
DRegionFromLUT8Image() treats zero as transparent and nonzero as opaque.

Release the container with DDisposeLUT8ImageContainer(). Call in task
context with decorator.library open; do not use zero dimensions.

See also

DDisposeLUT8ImageContainer() DRegionFromLUT8Image()

Synopsis

void DPutImageToRP(
   struct RastPort *rp, struct DecorImage *di, UWORD x, UWORD y)

Function

Copy an image to a RastPort and dispose of the image.

Inputs

rp - Non-NULL destination RastPort with a writable bitmap.
di - Image owned by the caller, or NULL to do nothing. Its data, when
    present, must contain di->w * di->h packed ARGB pixels. The row
    stride di->w * 4 must fit the pixel-array API's UWORD argument.
x, y - Destination top-left coordinates, in pixels.

Notes

Consumes di. Do not access or dispose of it after this call, and do
not pass a borrowed theme image. The image is disposed even when its
pixel buffer is absent or the pixel write fails. No status is returned.

Copies the full pixel buffer without alpha compositing or checking
ok. Bitmap caches are not used. The destination RastPort remains
owned by the caller.

See also

DGetImageFromRP() DDrawPartImageToRP() DDisposeImageContainer()

Synopsis

struct Region * DRegionFromLUT8Image(
   int w, int h, struct DecorImageLUT8 *s)

Function

Build a region from nonzero pixels in an eight-bit image.

Inputs

w, h - Intended overall region width and height. Use positive values
    representable by graphics Rectangle coordinates.
s - Live DecorImageLUT8 with readable, tightly packed data, or NULL.
    Its width and height must fit the region coordinate range.

Result

Owned Region, or NULL for a NULL source, failure to allocate a region,
or a detected rectangle-insertion failure. Release it with DisposeRegion().

Notes

Each nonzero source pixel contributes to opaque horizontal runs;
zero pixels are transparent. Source rows use s->w and s->h directly.
The function also adds the rectangle from (0, s->h) through (w-1, h-1)
below the source image. It does not scale or clip source runs to w or h;
use w >= s->w and h >= s->h for a containing extent.

The source buffer is borrowed only until return. Region construction
is synchronous and does not acquire a reference or lock the image.
Call in task context with decorator.library open.

Bugs

Failure to add a run ending at a transparent pixel is ignored; only
the lower rectangle and runs reaching the row end are checked. A
non-NULL result can therefore be incomplete after allocation failure.

See also

DNewLUT8ImageContainer() `DisposeRegion()`_

Synopsis

LONG DRenderElement(
   struct DecoratorElement *element, struct RastPort *rp, ULONG subimage, LONG xp, LONG yp, LONG dw, LONG dh, LONG clipw)

Function

Draw an image element using its type, source region and padding.

Inputs

element - Element descriptor, or NULL to do nothing.
rp - Destination RastPort, or NULL to do nothing.
subimage - Gadget state for DE_TYPE_STATEFUL_GADGET; grid row for
    horizontal tiling, column for vertical tiling, or source row
    selector for title tiling. Ignored for plain and repeated images.
xp, yp - Destination origin before de_PadX and de_PadY are added.
dw, dh - Requested extents. Meaning and valid ranges depend on type.
clipw - Positive absolute right limit for title tiling; otherwise ignored.

Result

Final y for vertical tiling, final x for horizontal/title tiling,
or padded xp for other types. A missing or invalid image returns
unpadded yp for vertical tiling, otherwise unpadded xp. NULL element
or rp returns unpadded xp regardless of type. Not a drawing status.

Notes

STATEFUL_GADGET scales the selected state to dw by dh; negative
sizes use natural dimensions. TILED_HORIZONTAL and TILED_VERTICAL
repeat de_SrcSize pixels starting at de_SrcOffset on their axis.
SCALED_TILED_H also scales to dh, using de_SrcHeight when positive
or image height divided by de_SubImageRows (zero means one row).
TILED_TITLE derives sy from subimage and de_SubImageRows, tiles to dw
and scales to dh. TILED_BOTH repeats the full image over dw by dh.
IMAGE copies the full image and ignores dw and dh. Unknown types
produce no output. de_Flags does not affect this function.

Padding moves the origin without shrinking the extents. Descriptor
row and column counts do not replace the image's own grid; keep them
consistent. Source rectangles, positive tile sizes and storage must
satisfy the corresponding drawing functions. State and repeated-image
sizes narrow to WORD, and some coordinates narrow to UWORD; keep
values representable. Inputs are borrowed and not modified.

Bugs

Title tiling does not honor its derived source height, so row
selection can read past the intended cell. Scaled types inherit
DScaleBuffer() allocation failures. No error status is available.

See also

DRenderElementChain() DWriteTiledImageTitle() DWriteTiledImageHorizontal() DWriteTiledImageVertical() DWriteVerticalScaledTiledImageHorizontal() DDrawScaledStatefulGadgetImageToRP() DHorizVertRepeatDecorImage() DDrawPartImageToRP()

Synopsis

LONG DRenderElementChain(
   struct DecoratorElement **elements, ULONG count, BOOL vertical, struct RastPort *rp, ULONG subimage, LONG xp, LONG yp, LONG dw, LONG dh)

Function

Lay out and draw an ordered chain of elements along one axis.

Inputs

elements - Array of count descriptor pointers. NULL entries are skipped.
count - Number of pointers in the array.
vertical - TRUE to advance y; FALSE to advance x.
rp - Destination RastPort with a writable bitmap.
subimage - State or subimage selector passed to each element.
xp, yp - Initial destination origin, in pixels.
dw, dh - Available extents; dh is the chain extent when vertical,
    otherwise dw. Provide nonnegative dimensions.

Result

Position after the positive sizes assigned to elements, on the chain
axis. NULL elements, NULL rp or zero count returns the starting axis
position. The result describes layout, not successful drawing.

Notes

Fixed elements use natural size on the chain axis: the full image
size for IMAGE, image size divided by the descriptor grid count for
STATEFUL_GADGET, and de_SrcSize for other types. A zero descriptor
grid count means one. A missing image contributes zero fixed size.

DEF_FILL elements share max(available - fixed, 0) equally; the first
such elements receive any remainder pixels. Other flags are ignored.
Entries assigned nonpositive sizes are not drawn or advanced. Fixed
sizes are not clipped to the available extent and can exceed it.

Each call to DRenderElement() receives clipw == 0. Padding changes
drawing positions but does not change the layout advance. An invalid
image can still occupy space; drawing return values are ignored.
There is no chain-level clipping or guarantee that an element draws
within its assigned size. Keep descriptors, source images and buffers
valid for the call, with nonnegative natural sizes and no arithmetic
overflow. All drawing preconditions of DRenderElement() still apply.
Inputs are borrowed; only the destination drawing state is changed.

See also

DRenderElement()

Synopsis

void DRenderMenuBackground(
   struct DecorImage *pic, struct DecorImage *texture, struct TileInfo *textureti, UWORD ratio)

Function

Blur an image and optionally mix a repeating menu texture into it.

Inputs

pic - Destination image with writable packed ARGB storage and positive
    dimensions. NULL or missing data is accepted only on the untiled path.
texture - Nonempty image with readable packed ARGB storage, or NULL
    for blur only. Its storage must not overlap pic.
textureti - Optional nine-part border geometry, used only with texture.
    Border sums must be less than the source dimensions and no larger
    than the destination dimensions.
ratio - Background percentage, normally 0 through 100. Values of 100
    or more suppress the final texture-color mix, but not the blur.

Notes

Without border geometry, repeats the texture over the blurred image.
With geometry, first builds a destination-sized nine-part texture;
its alpha controls the mix between original and blurred pixels.
The final color mix uses a truncated weight of 255 - 2.55 * ratio
when ratio < 100, with additional texture-alpha weighting on the
tiled path. Integer truncation means ratio 0 is not an exact copy.

The blur uses a 14-weight neighborhood with clamped edge samples.
Without a tiled texture it makes pixels opaque; with one it initially
sets alpha to the inverse texture alpha. A subsequent color mix sets
alpha to the texture alpha. Images are borrowed; only pic->data is
modified. The ok flags and bitmap caches are neither checked nor
updated.

Bugs

Failures are not reported. Failure to allocate blur rows skips the
blur but may still mix the texture. Failure to allocate the expanded
tiled texture falls back to the original texture without checking
that it covers pic, allowing out-of-bounds reads. Invalid border
geometry can produce incomplete output or nonterminating tiling.

See also

DRenderMenuBarBackground() DSetImageTint()

Synopsis

void DRenderMenuBarBackground(
   struct DecorImage *pic, struct DecorImage *texture, struct TileInfo *textureti, UWORD ratio)

Function

Build a menu-bar background from a tiled texture.

Inputs

pic - Non-NULL destination image with writable packed ARGB storage
    and positive dimensions.
texture - Nonempty image with readable packed ARGB storage, or NULL
    to do nothing. Its storage must not overlap pic.
textureti - Border geometry, or NULL to do nothing. Source border
    sums must leave a positive center width and height. Top plus
    bottom must fit pic->h; the right border must fit pic->w.
ratio - Background percentage, normally 0 through 100; 100 or more
    suppresses the final texture-color mix.

Notes

First fills pic with the texture's center tile. Then builds a tiled
texture with top, bottom and right borders; the left border is omitted.
Applies the blur, alpha handling and color mix described by
DRenderMenuBackground(). Unlike that function, processing starts from
the center-tile fill rather than the previous contents of pic.

Inputs are borrowed. Only pic->data changes; ok flags and bitmap
caches are neither checked nor updated. Exclude concurrent access
to the destination while rendering.

Bugs

Shares the unreported allocation failures and unsafe tiled-texture
fallback of DRenderMenuBackground(). The initial center fill may
already have changed pic when a later operation fails. Invalid source
tile dimensions can prevent termination.

See also

DRenderMenuBackground() DDrawPartToImage()

Synopsis

ULONG * DScaleBuffer(
   ULONG *srcdata, LONG widthBuffer, LONG widthSrc, LONG heightSrc, LONG widthDest, LONG heightDest)

Function

Scale a rectangular array of 32-bit pixels into a new packed buffer.

Inputs

srcdata - Non-NULL readable pixel pointer at the source rectangle's
    top-left pixel. Storage must remain valid until return.
widthBuffer - Source row stride in pixels, at least widthSrc.
widthSrc, heightSrc - Positive source dimensions, at most 65535 each.
widthDest, heightDest - Positive destination dimensions. Products,
    row offsets and scaling accumulators must fit target arithmetic.

Result

New widthDest*heightDest ULONG buffer on normal completion. Free it
with FreeVec(). Allocation failure is not reliably reported as NULL.

Notes

Scaling selects source samples without interpolation or color/alpha
conversion. All four bytes of a selected pixel are copied unchanged.
The output is tightly packed. The source is neither modified nor
retained; a subrectangle may use a larger source stride.

No bounds or arithmetic-overflow checks are performed. Source sample
indices use 16-bit storage. Provide enough source storage for all rows
and keep scaled sizes within the allocator's byte-size limit.

Call in task context with decorator.library open. Processing is
synchronous and has no cancellation or timeout.

Bugs

The output and horizontal sampling-table allocations are used without
NULL checks. Memory exhaustion can cause invalid memory access rather
than returning an error. Nonpositive dimensions are not supported.

See also

DScaleDecorImage() `FreeVec()`_

Synopsis

struct DecorImage * DScaleDecorImage(
   struct DecorImage *di, UWORD neww, UWORD newh)

Function

Create a scaled copy of an image pixel buffer.

Inputs

di - Live DecorImage with a non-NULL readable data buffer and positive
    dimensions. Its ok flag is not checked.
neww, newh - Positive destination dimensions whose allocation and
    scaling arithmetic fit the target's limits.

Result

Owned DecorImage on normal completion, or NULL if allocation of the
outer container fails. Deeper allocation failures are not reliably
reported. Dispose the result with DDisposeImageContainer().

Notes

The complete source pixel buffer is scaled using DScaleBuffer().
The subimage row and column counts are copied without validation;
choose destination dimensions that preserve any required grid layout.
The returned ok flag is TRUE after successful scaling.

Filename, datatype object, bitmap, mask and subimage decision table
are not copied. The result is a pixel-buffer image, not a screen-matched
copy or a filename-backed source for screen matching.

The source remains owned by the caller. Keep it stable until return.
Call synchronously in task context with decorator.library open.

See also

DScaleBuffer() DDisposeImageContainer()

Synopsis

void DSetImageTint(
   struct DecorImage *dst, UWORD ratio, ULONG argb)

Function

Mix a color into an image and make every pixel opaque.

Inputs

dst - Image with writable packed ARGB storage, or NULL to do nothing.
ratio - Tint weight from 0 through 255. Values are not clamped.
argb - Numeric 0xAARRGGBB tint color. The alpha byte is ignored.

Notes

For each RGB component, the result is:
    floor(tint * ratio / 256) + floor(original * (255 - ratio) / 256)
Every output alpha byte is 255. Neither endpoint is an exact copy:
ratio 0 darkens nonzero source components, and ratio 255 darkens
nonzero tint components.

Only the pixel buffer changes. The ok flag is not checked, and bitmap
caches are not refreshed. The image remains owned by the caller.
Exclude concurrent reads or writes while tinting.

See also

DWriteAlphaPixelArray() DDrawPartToImage()

Synopsis

void DShadeLine(
   LONG pen, BOOL tc, BOOL usegradients, struct RastPort *rp, struct DecorImage *di, ULONG basecolor, UWORD fact, UWORD offy, struct Rectangle *bounds)

Function

Draw a pen-colored or shaded line within inclusive bounds.

Inputs

pen - Foreground pen when tc is FALSE.
tc - FALSE for pen drawing; TRUE for shaded color or image drawing.
usegradients - With tc TRUE, select basecolor instead of image samples.
rp - Non-NULL destination RastPort with a writable bitmap.
di - Non-NULL image when tc is TRUE and usegradients is FALSE.
    A valid image needs positive dimensions and readable ARGB storage.
basecolor - Color in DecorImage's in-memory ARGB representation,
    read as a native ULONG; used only with tc and usegradients TRUE.
fact - Channel multiplier divided by 256; results saturate at 255.
    256 preserves each channel, including alpha.
offy - Ignored.
bounds - Non-NULL inclusive endpoints. Use nonnegative coordinates
    representable by WORD, ordered from minimum to maximum.

Notes

The pen and base-color paths draw between the endpoints and leave
RastPort drawing state changed. The base-color path disables pen mode.
With a valid image, the function shades image samples repeated at the
layer coordinates and processes the bounded rectangle. Use a single
row or column for line drawing. Sampling coordinates must be
nonnegative and image storage must remain valid throughout the call.

An image with ok == FALSE falls back to drawing with the current
RastPort color and mode. Reversed endpoints produce no drawing.
The image is borrowed and is not modified.

Bugs

offy does not affect sampling. Multirow, multicolumn image shading
can repeatedly overwrite the first output row when a line buffer is
used. Negative sampling coordinates are not consistently normalized.
The base-color path passes native ARGB storage directly as a RastPort
color, so channel order can be wrong on little-endian targets.

See also

DDrawPartImageToRP() DFillPixelArrayGradient()

Synopsis

void DTileMapToBitmap(
   struct DecorImage *src, struct TileInfo *srcti, struct BitMap *map, UWORD dw, UWORD dh)

Function

Fill a bitmap rectangle with a nine-part image tile map.

Inputs

src - Source image with ok == TRUE and a valid bitmap field.
srcti - Border widths and heights in pixels. Left plus right must be
    less than src->w; top plus bottom must be less than src->h.
map - Writable destination bitmap.
dw, dh - Destination dimensions, in pixels, within map. Border sums
    must not exceed these dimensions.

Notes

Draws at destination (0, 0). Corners retain their dimensions; edges
and the center repeat, with partial tiles cropped at the far edges.
The source mask is applied when present. Pixel data and bitmap2 are
not used as alternative sources.

NULL src, srcti or map, a false ok flag, or border sums larger than
the destination produce no drawing. Failure to allocate a RastPort
also produces no drawing and is not reported.

Source border geometry is not validated. A zero center-tile dimension
can prevent the tiling loop from terminating. All source rectangles
must lie within the source bitmap. Inputs are borrowed; keep their
storage valid and exclude concurrent modification during use.

See also

DHorizVertRepeatDecorImage() DCreateDecorImageContainerMatchingScreen()

Synopsis

void DWriteAlphaPixelArray(
   struct DecorImage *src, struct DecorImageLUT8 *dst, LONG sx, LONG sy, LONG dx, LONG dy, LONG w, LONG h)

Function

Copy an image rectangle's alpha bytes into an 8-bit image.

Inputs

src - Non-NULL image with readable packed ARGB storage.
dst - Non-NULL 8-bit image with writable storage.
sx, sy - Nonnegative source top-left coordinates, in pixels.
dx, dy - Nonnegative destination top-left coordinates, in pixels.
w, h - Positive rectangle dimensions, within both image buffers.

Notes

Writes one alpha byte per pixel, preserving its value from 0 through
255. No blending, thresholding or color conversion is performed.
Rows use src->w pixels and dst->w bytes as their respective strides.

The buffers must not overlap. Bounds, pointers and ok flags are not
checked. Images are borrowed; exclude concurrent source modification
and destination access while copying. Metadata is unchanged.

See also

DNewLUT8ImageContainer() DRegionFromLUT8Image() DDrawPartToImage()

Synopsis

LONG DWriteTiledImageHorizontal(
   struct RastPort *rp, struct DecorImage *di, ULONG subimage, LONG sx, LONG sw, LONG xp, LONG yp, LONG dw)

Function

Repeat a strip from an image row horizontally at its natural height.

Inputs

rp - Non-NULL destination RastPort with a writable bitmap.
di - Non-NULL image with nonzero grid counts and positive cell sizes.
subimage - Grid row index; column 0 is used.
sx - Nonnegative source x offset within the selected cell.
sw - Positive strip width within that cell; zero draws nothing.
xp, yp - Destination top-left coordinates, in pixels.
dw - Horizontal extent to fill. Nonpositive values draw nothing.

Result

Final x position, normally xp + dw. Returns xp if ok is FALSE,
sw is zero or dw is nonpositive. An out-of-range row produces no
pixels but still advances the result. This is not a success status.

Notes

Repeats the source strip, cropping the last tile horizontally. Uses
the natural grid-cell height and performs no scaling. Transparency
and cache selection follow DDrawStatefulGadgetImageToRP().

Negative sw is invalid and can prevent termination. Source bounds
are not checked. Keep source storage live, ARGB row strides within
UWORD range, and destination coordinates and extents within graphics
interface limits. The image is borrowed and is not modified.

See also

DWriteTiledImageVertical() DWriteVerticalScaledTiledImageHorizontal()

Synopsis

LONG DWriteTiledImageTitle(
   BOOL fill, struct Window *win, struct RastPort *rp, struct DecorImage *di, LONG sx, LONG sy, LONG sw, LONG sh, LONG xp, LONG yp, LONG dw, LONG dh)

Function

Repeat an image strip horizontally, optionally scaling its height.

Inputs

fill - Ignored.
win - Window whose Width limits the destination's right edge, or NULL
    for no additional width limit. Does not select the RastPort.
rp - Non-NULL destination RastPort with a writable bitmap.
di - Non-NULL image with a valid nonempty subimage grid and storage.
sx, sy - Nonnegative source offsets relative to grid cell (0, 0).
sw - Positive strip width; zero draws nothing. Negative values are invalid.
sh - Ignored; source height is the natural grid-cell height.
xp, yp - Destination top-left coordinates, in pixels.
dw - Horizontal extent to fill. Nonpositive values draw nothing.
dh - Positive output height, or -1 for natural cell height. Zero is invalid.

Result

Final x position after the requested tiles, limited by win->Width
when positive. Returns xp if ok is FALSE or no tiles are processed.
The result does not report successful pixel output.

Notes

Repeats the same source strip and crops the last tile horizontally.
The full natural cell height is read starting at sy, so that entire
rectangle must fit the image. Scaling and transparency follow
DDrawScaledStatefulGadgetImageToRP(). Keep coordinates, row strides
and size calculations within the called graphics interfaces' ranges.
The image and optional window are borrowed for the call.

Bugs

sh is not used to limit source reads. A nonzero sy can make the
natural-height read extend beyond the intended cell or image.
Height scaling inherits unchecked allocation failures from DScaleBuffer().

See also

DWriteTiledImageHorizontal() DDrawScaledStatefulGadgetImageToRP()

Synopsis

LONG DWriteTiledImageVertical(
   struct RastPort *rp, struct DecorImage *di, ULONG subimage, LONG sy, LONG sh, LONG xp, LONG yp, LONG dh)

Function

Repeat a strip from an image column vertically at its natural width.

Inputs

rp - Non-NULL destination RastPort with a writable bitmap.
di - Non-NULL image with nonzero grid counts and positive cell sizes.
subimage - Grid column index; row 0 is used.
sy - Nonnegative source y offset within the selected cell.
sh - Positive strip height within that cell; zero draws nothing.
xp, yp - Destination top-left coordinates, in pixels.
dh - Vertical extent to fill. Nonpositive values draw nothing.

Result

Final y position, normally yp + dh. Returns yp if ok is FALSE,
sh is zero or dh is nonpositive. An out-of-range column produces no
pixels but still advances the result. This is not a success status.

Notes

Repeats the source strip, cropping the last tile vertically. Uses
the natural grid-cell width and performs no scaling. Transparency
and cache selection follow DDrawStatefulGadgetImageToRP().

Negative sh is invalid and can prevent termination. Source bounds
are not checked. Keep source storage live, ARGB row strides within
UWORD range, and destination coordinates and extents within graphics
interface limits. The image is borrowed and is not modified.

See also

DWriteTiledImageHorizontal() DDrawStatefulGadgetImageToRP()

Synopsis

LONG DWriteVerticalScaledTiledImageHorizontal(
   struct RastPort *rp, struct DecorImage *di, ULONG subimage, LONG sx, LONG sw, LONG xp, LONG yp, LONG sh, LONG dw, LONG dh)

Function

Repeat an image strip horizontally while scaling its height.

Inputs

rp - Non-NULL destination RastPort with a writable bitmap.
di - Non-NULL image with nonzero grid counts and positive cell sizes.
subimage - Grid row index; column 0 is used.
sx - Nonnegative source x offset within the selected cell.
sw - Positive strip width within that cell; zero draws nothing.
xp, yp - Destination top-left coordinates, in pixels.
sh - Positive source height within the selected cell, or -1 for its
    natural height. Source y offset is zero.
dw - Horizontal extent to fill. Nonpositive values draw nothing.
dh - Positive output height, or -1 to use the selected source height.
    Zero sh or dh is invalid.

Result

Final x position, normally xp + dw. Returns xp if ok is FALSE,
sw is zero or dw is nonpositive. An out-of-range row produces no
pixels but still advances the result. This is not a success status.

Notes

Repeats the same strip, cropping the last tile horizontally. Negative
sh or dh selects the natural source height or selected source height,
respectively. When heights differ, requires readable ARGB data even
if bitmap caches exist. Scaling and transparency follow
DDrawScaledStatefulGadgetImageToRP().

Negative sw is invalid and can prevent termination. Source bounds
are not checked. Inputs are borrowed; keep source storage valid and
all dimensions, strides and products within DScaleBuffer() and the
pixel-array interfaces' limits.

Bugs

Height scaling inherits unchecked allocation failures from DScaleBuffer().

See also

DWriteTiledImageHorizontal() DDrawScaledStatefulGadgetImageToRP()