PUT（图形）

• 来源: https://www.freebasic.net/wiki/wikka.php?wakka=KeyPgPutgraphics
• 最后更新: 2023-07-09

---

将图像复制到另一图像或屏幕上

语法

Put [target, ] [ [STEP](x, y), source [, (x1, y1)-[STEP](x2, y2) ] [, method [, ( alphaval|value|blender [, param]) ] ]

参数

target

要绘制图像的缓冲区地址。如果省略，图像将位图传输到屏幕。见下文。

[STEP](x, y)

指定目标缓冲区或屏幕左上角的偏移量，图像将绘制到该位置。STEP 表示 (x, y) 偏移量相对于当前图形光标位置。

source

要绘制的图像缓冲区地址。见下文。

(x1, y1)-[STEP](x2, y2)

指定源缓冲区中要绘制的矩形区域。如果省略，绘制整个缓冲区。STEP 表示 x2 和 y2 分别相对于 x1 和 y1。

method

指定将图像绘制到目标缓冲区所用的方法，可以是以下任意一种（默认方法为 XOR）：

与背景无关的方法

PSET：源像素值不经修改直接复制。

PRESET：源像素值取反补码后再复制。

TRANS：源像素值不经修改直接复制。不绘制遮罩颜色的源像素。见下文。

与背景相关的方法

AND (Graphics Put)：目标像素与源像素进行位运算 AND。见下文。

OR：目标像素与源像素进行位运算 OR。见下文。

XOR：目标像素与源像素进行位运算 XOR。见下文。

ALPHA：源图像以 value 参数或图像各个像素中指定的透明度因子与目标混合。见下文。

ADD：源图像乘以一个值后与目标进行饱和加法。见下文。

CUSTOM：使用用户定义的函数执行源图像与目标的混合。见下文。

value

0..255 的值，为 ADD 或 ALPHA 方法位图传输指定透明度值。

blender

指定在 CUSTOM 方法位图传输中要调用的用户定义函数地址。见下文。

param

指定传递给自定义混合函数的参数。

说明

Put 语句可用于将图像绘制到另一图像或屏幕上。x 和 y 坐标受上次调用 View 和 Window 语句的影响，绘制的图像遵守上次调用 View 语句设置的当前裁剪区域。源图像可以溢出目标缓冲区或屏幕（复制的图像会相应地被裁剪）。

有效图像缓冲区

source 和 target 图像缓冲区必须是有效的图像缓冲区。有效图像缓冲区使用 Get 或 ImageCreate 语句创建。在 Put 语句中，有效图像缓冲区可以用可选索引的数组名（但不能用空括号），或带可选索引的指针来指定。

绘制方法

根据所用方法，目标缓冲区中现有的像素值用于计算实际绘制的像素值。PSET、PRESET 和 TRANS 方法不使用目标缓冲区计算最终像素值，而 AND、OR、XOR、ALPHA 和 ADD 方法会使用。使用后几种方法绘制的图像将根据目标缓冲区的内容呈现不同效果。

不同像素格式

图像缓冲区的像素格式必须与当前图形模式的颜色深度兼容；即如果使用 Get 获取图像后通过 Screen (Graphics) 语句更改屏幕模式，图像数据在新图形模式中可能无效，可能无法在屏幕上绘制。但请注意，只要缓冲区使用相同深度创建，始终可以通过 Put 将图像缓冲区绘制到其他图像缓冲区上。

AND、OR 和 XOR 方法根据当前颜色深度产生不同结果，因为像素以不同格式存储；详情参见内部像素格式。

遮罩颜色

TRANS、ALPHA 和 ADD 方法不绘制源图像中使用遮罩颜色的像素。遮罩颜色取决于目标（图像缓冲区或屏幕）深度：在不超过 8bpp 的深度（调色板模式）中等于颜色索引 0，在高彩/真彩深度（16 和 32bpp）中等于品红色，即 RGB(255, 0, 255)。请注意，在 32bpp 模式下，颜色的 alpha 值不影响透明颜色的识别；只有低 24 位用于识别。详情参见内部像素格式。

Alpha 绘制

ALPHA 方法可以两种模式使用。如果指定了 value 参数，用于为整个待绘制图像指定透明度级别；值为 0 将绘制完全透明的图像，值为 255 将绘制完全不透明的图像。此模式仅在绘制到高彩/真彩目标（16 和 32bpp）时有效。

如果省略 value 参数，ALPHA 方法将逐像素获取 alpha 级别值，允许绘制带 alpha 通道的图像（图像的某些部分可以比其他部分更透明或更不透明）。此模式仅适用于 32bpp 图像缓冲区，因为这是唯一允许每个像素嵌入 alpha 值的颜色深度。

处理 alpha 通道

通常 Put 只允许将图像缓冲区绘制到相同深度的目标上，但有一个例外。当将 8bpp 图像缓冲区绘制到 32bpp 目标上并使用 ALPHA 方法时，8bpp 源图像被绘制到 32bpp 目标的 alpha 通道中。这样可以轻松设置图像的整个 alpha 通道，而无需处理其像素数据的底层访问。

自定义混合函数

CUSTOM 方法使用用户定义的函数来计算要绘制到目标缓冲区的最终像素值。该函数将对源图像的每个像素调用一次，并接收源像素值和目标像素值，以及 Put 函数传递的数据指针。返回的像素值将用于绘制到目标缓冲区。函数形式如下：

declare function identifier ( byval source_pixel as ulong, byval destination_pixel as ulong, byval parameter as any ptr ) as ulong

identifier 是函数名称。可以是任何名称。

source_pixel 是源图像的当前像素值。

destination_pixel 是目标图像的当前像素值。

parameter 是 Put 命令传递的参数。应为数据指针。如果省略，其值为零。

示例

以下程序给出了如何将图像 Put 到屏幕的简单示例，包括设置图像缓冲区和之后释放其内存：

start GeSHi

'' set up the screen and fill the background with a color
ScreenRes 320, 200, 32
Paint (0, 0), RGB(64, 128, 255)

'' set up an image and draw something in it
Dim img As Any Ptr = ImageCreate( 32, 32, RGB(255, 0, 255) )
Circle img, (16, 16), 15, RGB(255, 255, 0),     ,     , 1, f
Circle img, (10, 10), 3,  RGB(  0,   0, 0),     ,     , 2, f
Circle img, (23, 10), 3,  RGB(  0,   0, 0),     ,     , 2, f
Circle img, (16, 18), 10, RGB(  0,   0, 0), 3.14, 6.28

'' PUT the image in the center of the screen
Put (160 - 16, 100 - 16), img, Trans

'' free the image memory
ImageDestroy img

'' wait for a keypress
Sleep

end GeSHi

以下示例展示了如何为图像分配内存，使用各种方法（包括自定义混合函数）绘制图像，以及释放图像内存：

start GeSHi

Declare Function checkered_blend( ByVal src As ulong, ByVal dest As ulong, ByVal param As Any Ptr ) As ulong

   Screen 14, 32                                   '' set 320*240*32 gfx mode
   
   Dim As Any Ptr sprite
   Dim As Integer counter = 0
   
   sprite = ImageCreate( 32, 32 )                  '' allocate memory for 32x32 sprite
   
   Line sprite, ( 0, 0 )-( 31, 31 ), RGBA(255, 0, 0, 64), bf  '' draw a sprite ...
   Line sprite, ( 4, 4 )-( 27, 27 ), RGBA(255, 0, 0, 192), bf
   Line sprite, ( 0, 0 )-( 31, 31 ), RGB(0, 255, 0), b
   Line sprite, ( 8, 8 )-( 23, 23 ), RGBA(255, 0, 255, 64), bf
   Line sprite, ( 1, 1 )-( 30, 30 ), RGBA(0, 0, 255, 192)
   Line sprite, ( 30, 1 )-( 1, 30 ), RGBA(0, 0, 255, 192)
   
   Cls
   Dim As Integer i : For i = 0 To 63              '' draw the background
      Line( i,0 )-( i,240 ), RGB( i * 4, i * 4, i * 4 )
   Next i
   
   '' demonstrate all drawing methods ...
   Put( 8,14 ), sprite, PSet
   Put Step( 16,20 ), sprite, PReset
   Put Step( -16,20 ), sprite, And
   Put Step( 16,20 ), sprite, Or
   Put Step( -16,20 ), sprite, Xor
   Put Step( 16,20 ), sprite, Trans
   Put Step( -16,20 ), sprite, Alpha, 96
   Put Step( 16,20 ), sprite, Alpha
   Put Step( -16,20 ), sprite, add, 192
   Put Step( 16,20 ), sprite, Custom, @checkered_blend, @counter
   
   '' print a description near each demo
   Draw String (100, 26), "<- pset"
   Draw String Step (0, 20), "<- preset"
   Draw String Step (0, 20), "<- and"
   Draw String Step (0, 20), "<- or"
   Draw String Step (0, 20), "<- xor"
   Draw String Step (0, 20), "<- trans"
   Draw String Step (0, 20), "<- alpha (uniform)"
   Draw String Step (0, 20), "<- alpha (per pixel)"
   Draw String Step (0, 20), "<- add"
   Draw String Step (0, 20), "<- custom"
   
   ImageDestroy( sprite )                          '' free allocated memory for sprite
   Sleep : End 0

'' custom blender function: chequered put
Function checkered_blend( ByVal src As ulong, ByVal dest As ulong, ByVal param As Any Ptr ) As ulong
   Dim As Integer Ptr counter
   Dim As ulong pixel
   
   counter = Cast(Integer Ptr, param)
   pixel = IIf(((*counter And 4) Shr 2) Xor ((*counter And 128) Shr 7), src, dest)
   *counter += 1
   Return pixel
End Function

end GeSHi

与 QB 的区别

• target 是 FreeBASIC 新增的
• TRANS、ALPHA、ADD 和 CUSTOM 方法是 FreeBASIC 新增的
• FB 内部使用不同的图像格式，QB 不支持该格式
• QB 会抛出运行时错误而不是裁剪越界图像
• 在 QB 中，只有数组可以指定为源图像

另请参阅

• Custom (Graphics Put)
• Put (File I/O)
• Get (Graphics)
• ImageCreate
• Alpha
• 内部像素格式

返回 目录