ImgAddSize - ProGUI Reference Manual

Syntax

Success = ImgAddSize(Img, SrcImg)

Description

Adds an alternative size representation (SrcImg) to an existing ProGUI image object (Img). This allows ProGUI's rendering system to automatically select the most appropriate image size from the available variants when drawing the base image (Img) at different scaled sizes, improving quality and performance, especially for DPI scaling or icons.

Parameters

Img
The handle of the base ProGUI image object to which the alternative size will be added.

SrcImg
The handle of the ProGUI image object representing the alternative size.

Return Value

Returns #True if the alternative size was successfully added or updated. Returns #False if either handle is invalid, if Img and SrcImg are the same, or if SrcImg has the same dimensions as Img or an already existing alternative size for Img.

Remarks

When DrawImg() or an image brush is used, ProGUI checks the target rendering size (considering DPI scaling) and selects the variant from Img's internal list (including the base Img itself and any added via ImgAddSize) that has the closest dimensions greater than or equal to the target size. If no larger size is available, the largest available variant is used.

This is particularly useful for loading multi-size icon files (.ico). You can load the smallest size as the base Img and then add the larger sizes using ImgAddSize(). ProGUI increments the reference count of SrcImg when it's added. You should still call FreeImg() on your handle to SrcImg after adding it; the image data will persist as long as the base Img holds a reference. If an image with the exact dimensions of SrcImg already exists as a variant for Img, the existing variant's image handle will be replaced (and its reference count decremented) with SrcImg. The internal list of alternate sizes is kept sorted by width.

Example

IncludeFile "ProGUI_PB.pbi"

StartProGUI()

; Assume the png images exist
Global BaseIcon = LoadImg("Icons\testMultiIcon\testMultiIcon2-13.png") ; 16 x 16
Icon32 = LoadImg("Icons\testMultiIcon\testMultiIcon2-12.png") ; 32 x 32
Icon64 = LoadImg("Icons\testMultiIcon\testMultiIcon2-11.png") ; 64 x 64

Procedure DrawHandler(Widget, EventType, *EventData.PG_EventDraw)
  ; Draw the base icon at different sizes. ProGUI selects the best variant.
  DrawImg(BaseIcon, 10, 10, 16, 16)  ; Should use 16x16
  DrawImg(BaseIcon, 40, 10, 24, 24)  ; Should use 32x32 (closest >=)
  DrawImg(BaseIcon, 80, 10, 32, 32)  ; Should use 32x32
  DrawImg(BaseIcon, 130, 10, 48, 48) ; Should use 64x64 (closest >=)
  DrawImg(BaseIcon, 200, 10, 64, 64) ; Should use 64x64
  DrawImg(BaseIcon, 280, 10, 96, 96) ; Should use 64x64 (largest available)
EndProcedure

If BaseIcon And Icon32 And Icon64
  Debug "Base icon (16x16) loaded."

  ; Add the larger sizes as variants
  If ImgAddSize(BaseIcon, Icon32)
    Debug "Added 32x32 variant."
  EndIf
  If ImgAddSize(BaseIcon, Icon64)
    Debug "Added 64x64 variant."
  EndIf

  ; Now you only need to keep track of BaseIcon. ProGUI will pick the best size when drawing.
  MyWindow = CreateWindow(0, 0, 400, 200, "Multi-Size Image")
  If MyWindow
    RootLayout = WindowGetLayout(MyWindow)
    LayoutSetPadding(RootLayout, 20)
    Widget = CreateWidget(0,0,400,400) ; Create a widget to draw on
    AddEventHandler(Widget, #PG_Event_Draw, @DrawHandler())
    WindowShow(MyWindow, #True, #PG_Window_ScreenCentered)

    Repeat : Event = WaitWindowEvent() : Until Event = #PB_Event_CloseWindow
  EndIf

  ; Free your references. The image data might still be held by BaseIcon.
  FreeImg(Icon32)
  FreeImg(Icon64)
  FreeImg(BaseIcon) ; This will free all variants if ref count reaches 0

Else
  Debug "Error loading one or more icons."
  If BaseIcon : FreeImg(BaseIcon) : EndIf
  If Icon32 : FreeImg(Icon32) : EndIf
  If Icon64 : FreeImg(Icon64) : EndIf
EndIf

StopProGUI()

Supported OS

Windows, Linux