Class: Fox::FXImage

Inherits:
FXDrawable show all
Defined in:
rdoc-sources/FXImage.rb,
lib/fox16/core.rb

Overview

An Image is a rectangular array of pixels. It supports two representations of these pixels: a client-side pixel buffer which is stored as an array of FXColor, and a server-side pixmap which is stored in an organization directly compatible with the screen, for fast drawing onto the device. The server-side representation is not directly accessible from the current process as it lives in the process of the X Server or GDI.

Image rendering hints

IMAGE_KEEP

Keep pixel data in client. By default, FOX discards of the client-side pixel data for an image after you call create() for that image. When the IMAGE_KEEP option is set for FXImage (or one of its subclasses), the client-side buffer is maintained. You will typically want to set this option if you intend to do repeated re-rendering of the image after it has been created.

IMAGE_OWNED

If IMAGE_OWNED is set, the image pixel data is copied into the image. If IMAGE_OWNED is not set, a image pixel string is directly used as memory buffer of the image, without copying the data. If pixel data is given as an Array instead of a string, data is copied in any case.

IMAGE_DITHER

Dither image to look better

IMAGE_NEAREST

Turn off dithering and map to nearest color

IMAGE_OPAQUE

Force opaque background

IMAGE_ALPHACOLOR

By default, FOX will use the transparency color obtained from the image file as the transparency (alpha) color. If you pass the IMAGE_ALPHACOLOR flag, the user-specified transparency color will be used instead.

IMAGE_SHMI

Using shared memory image

IMAGE_SHMP

Using shared memory pixmap

IMAGE_ALPHAGUESS

Guess transparency color from corners

Instance Attribute Summary collapse

Attributes inherited from FXDrawable

#height, #visual, #width

Attributes inherited from FXId

#app, #userData, #xid

Instance Method Summary collapse

Methods inherited from FXDrawable

#resize

Methods inherited from FXId

#create, #created?, #destroy, #detach, #runOnUiThread

Methods inherited from FXObject

#bind, #handle, #load, #save, subclasses

Constructor Details

#initialize(a, pix, *args) ⇒ FXImage

Create an image. If a client-side pixel buffer has been specified, the image owns the pixel buffer. If the IMAGE_OWNED flag is set but a nil pixel buffer is passed, a pixel buffer will be automatically created and will be owned by the image. The flags IMAGE_SHMI and IMAGE_SHMP may be specified for large images to instruct #render to use shared memory to communicate with the server.

Parameters:

a

an application instance Fox::FXApp

pixels

pixels [Array of FXColor values or string of raw [RGBA] values]

opts

image options [Integer]

width

image width [Integer]

height

image height [Integer]



77
78
 
# File 'rdoc-sources/FXImage.rb', line 77

def initialize(a, pixels=nil, opts=0, width=1, height=1) # :yields: theImage
end

Instance Attribute Details

#data ⇒ Object (readonly)

deprecated

Pixel data Fox::FXMemoryBuffer



46
47
48
 
# File 'rdoc-sources/FXImage.rb', line 46

def data
  @data
end

#dataPtr ⇒ Object (readonly)

The pointer to the raw color representation of all image pixels.

It can be used to pass raw image data to FFI, Fiddle or OpenGL.



51
52
53
 
# File 'rdoc-sources/FXImage.rb', line 51

def dataPtr
  @dataPtr
end

#options ⇒ Object

Option flags [Integer]



58
59
60
 
# File 'rdoc-sources/FXImage.rb', line 58

def options
  @options
end

#pixels ⇒ Object

Array of colors of all image pixels. Can also be written as String of raw [RGBA] values.



54
55
56
 
# File 'rdoc-sources/FXImage.rb', line 54

def pixels
  @pixels
end

Instance Method Details

#blend(color) ⇒ Object

Blend image over uniform color.

Parameters:

color

the blended color Fox::FXColor



292
 
# File 'rdoc-sources/FXImage.rb', line 292

def blend(color); end

#crop(x, y, w, h, color = 0) ⇒ Object

Crop image to given rectangle and then re-render the server-side image from the client-side pixel buffer. This method calls resize() to adjust the client and server side representations. The new image may be smaller or larger than the old one; blank areas are filled with color. There must be at least one pixel of overlap between the old and the new image.

Parameters:

x

x-coordinate for top left corner of the clip rectangle [Integer]

y

y-coordinate for top left corner of the clip rectangle [Integer]

width

width of the clip rectangle [Integer]

height

height of the clip rectangle [Integer]

color

fill color for blank areas after crop Fox::FXColor



210
 
# File 'rdoc-sources/FXImage.rb', line 210

def crop(x, y, w, h, color=0) ; end

#fade(color, factor = 255) ⇒ Object

Fade an image to a certain color by a certain factor. The factor is some integer value between 0 and 255 inclusive, where a factor of 255 indicates no fading and a factor of zero indicates that the image is completely faded to the fade color.

Parameters:

color

the fade color Fox::FXColor

factor

fading factor [Integer]



225
 
# File 'rdoc-sources/FXImage.rb', line 225

def fade(color, factor=255); end

#fill(color) ⇒ Object

Fill image with uniform color.



213
 
# File 'rdoc-sources/FXImage.rb', line 213

def fill(color); end

#getPixel(x, y) ⇒ Object

Return the color of the pixel at (x, y).

Parameters:

x

x-coordinate of the pixel of interest [Integer]

y

y-coordinate of the pixel of interest [Integer]



115
 
# File 'rdoc-sources/FXImage.rb', line 115

def getPixel(x, y) ; end

#gradient(topleft, topright, bottomleft, bottomright) ⇒ Object

Fill image using a bilinear gradient.

Parameters:

topleft

pixel color for top-left corner Fox::FXColor

topright

pixel color for top-right corner Fox::FXColor

bottomleft

pixel color for bottom-left corner Fox::FXColor

bottomright

pixel color for bottom-right corner Fox::FXColor



283
 
# File 'rdoc-sources/FXImage.rb', line 283

def gradient(topleft, topright, bottomleft, bottomright); end

#hasAlpha? ⇒ Boolean

Scan the image and return false if it’s fully opaque.

Returns:

  • (Boolean) 


129
 
# File 'rdoc-sources/FXImage.rb', line 129

def hasAlpha?; end

#hgradient(left, right) ⇒ Object

Fill image using a horizontal gradient.

Parameters:

left

starting color, for leftmost pixels Fox::FXColor

right

ending color, for rightmost pixels Fox::FXColor



261
 
# File 'rdoc-sources/FXImage.rb', line 261

def hgradient(left, right); end

#initialize_without_data_string ⇒ FXImage

Create an image. If a client-side pixel buffer has been specified, the image owns the pixel buffer. If the IMAGE_OWNED flag is set but a nil pixel buffer is passed, a pixel buffer will be automatically created and will be owned by the image. The flags IMAGE_SHMI and IMAGE_SHMP may be specified for large images to instruct #render to use shared memory to communicate with the server.

Parameters:

a

an application instance Fox::FXApp

pixels

pixels [Array of FXColor values or string of raw [RGBA] values]

opts

image options [Integer]

width

image width [Integer]

height

image height [Integer]

Returns:

  • (FXImage) —

    a new instance of FXImage



693
694
 
# File 'lib/fox16/core.rb', line 693

def initialize(a, pixels=nil, opts=0, width=1, height=1) # :yields: theImage
end

#loadPixels(store) ⇒ Object

Load pixel data from a stream.

Note that the base class version of #loadPixels expects to read the the pixel data in a neutral format (i.e. without any image format specific information). For example, if you have a 1024x768 image without an alpha channel (and thus only the red, green and blue channels), #loadPixels will attempt to read a total of 1024*768*3*8 bytes from the stream. The behavior of #loadPixels is different for subclasses such as FXPNGImage, where #loadPixels will instead expects to read the image data in a specific image file format (i.e. the PNG file format).

Parameters:

store

opened stream from which to read the pixel data Fox::FXStream



329
 
# File 'rdoc-sources/FXImage.rb', line 329

def loadPixels(store) ; end

#mirror(horizontal, vertical) ⇒ Object

Mirror image horizontally and/or vertically and then re-render the server-side image from the client-side pixel buffer.

Parameters:

horizontal

if true, the image will be flipped from left to right [Boolean]

vertical

if true, the image will be flipped from top to bottom [Boolean]



183
 
# File 'rdoc-sources/FXImage.rb', line 183

def mirror(horizontal, vertical) ; end

#pixel_string(offset = nil, size = nil) ⇒ Object

Return a String of the raw color representation of all image pixels.

Image pixels are stored bytewise as [RGBA] values.

Optional offset and size can be used to retrieve a part of the image data. Both are counted in bytes.



105
 
# File 'rdoc-sources/FXImage.rb', line 105

def pixel_string(offset=nil, size=nil) ; end

#release ⇒ Object

Release the client-side pixels buffer, free it if it was owned (i.e. if the IMAGE_OWNED option is set).. If it is not owned, the image just forgets about the buffer.



152
 
# File 'rdoc-sources/FXImage.rb', line 152

def release(); end

#render ⇒ Object

Render the image from client-side pixel buffer, if there is data and if the image width and height are greater than zero.



145
 
# File 'rdoc-sources/FXImage.rb', line 145

def render() ; end

#restore ⇒ Object

Restore client-side pixel buffer from image. This operation overwrites any current values for the client-side pixel buffer with values corresponding to the server-side image. If the image data is nil at the time #restore is called, the image will first allocate an (owned) pixel buffer to use for this operation.



139
 
# File 'rdoc-sources/FXImage.rb', line 139

def restore() ; end

#rotate(degrees) ⇒ Object

Rotate image counter-clockwise by some number of degrees and then re-render the server-side image from the client-side pixel buffer.

Parameters:

degrees

number of degrees by which to rotate the image [Integer]



193
 
# File 'rdoc-sources/FXImage.rb', line 193

def rotate(degrees) ; end

#savePixels(store) ⇒ Object

Save pixel data to a stream.

Note that the base class version of #savePixels saves the pixel data as-is, without any image format specific information. For example, if you have a 1024x768 image without an alpha channel (and thus only the red, green and blue channels) the total number of bytes written to the stream will be 1024*768*3*8. The behavior of #savePixels is different for subclasses such as FXPNGImage, where #savePixels will instead save the image data in a specific image file format (i.e. the PNG file format).

Parameters:

store

opened stream to which to save the pixel data Fox::FXStream



310
 
# File 'rdoc-sources/FXImage.rb', line 310

def savePixels(store) ; end

#scale(w, h, quality = 0) ⇒ Object

Rescale pixels image to the specified width and height and then re-render the server-side image from the client-side pixel buffer. Note that this serves a slightly different purpose than the base class resize() method, which simply resizes the client-side pixel data buffer but doesn’t transform the image.

The optional third argument specifies the quality of the scaling algorithm used. By default, #scale uses a fast (but low quality) nearest-neighbor algorithm for scaling the image to its new size. To use the higher-quality scaling algorithm from FOX 1.0, you should pass in a value of 1 as the third argument to #scale.

Parameters:

width

new image width, in pixels [Integer]

height

new image height, in pixels [Integer]

quality

scaling algorithm quality, either 0 or 1 (see above) [Integer]



172
 
# File 'rdoc-sources/FXImage.rb', line 172

def scale(w, h, quality=0) ; end

#setPixel(x, y, clr) ⇒ Object

Set pixel at (x, y) to clr.

Parameters:

x

x-coordinate of the pixel of interest [Integer]

y

y-coordinate of the pixel of interest [Integer]

clr

new color value for this pixel Fox::FXColor



126
 
# File 'rdoc-sources/FXImage.rb', line 126

def setPixel(x, y, clr) ; end

#setPixels(pix, *args) ⇒ Object

Populate the image with new pixel data of the same size or of a new size

Pixel data is copied and IMAGE_OWNED option is set. If called with width and height, the size of the serverside representation of the image, if it exists, is adjusted but the contents are not updated yet. This can be done by calling render().

Parameters:

pixels

pixels [Array of FXColor values or string of raw [RGBA] values]

opts

image options [Integer]

width

image width [Integer]

height

image height [Integer]



95
96
 
# File 'rdoc-sources/FXImage.rb', line 95

def setPixels(pixels, opts=0, width=nil, height=nil)
end

#setPixels_without_data_string ⇒ Object

Populate the image with new pixel data of the same size or of a new size

Pixel data is copied and IMAGE_OWNED option is set. If called with width and height, the size of the serverside representation of the image, if it exists, is adjusted but the contents are not updated yet. This can be done by calling render().

Parameters:

pixels

pixels [Array of FXColor values or string of raw [RGBA] values]

opts

image options [Integer]

width

image width [Integer]

height

image height [Integer]



699
700
 
# File 'lib/fox16/core.rb', line 699

def setPixels(pixels, opts=0, width=nil, height=nil)
end

#vgradient(top, bottom) ⇒ Object

Fill image using a vertical gradient.

Parameters:

top

starting color, for topmost pixels Fox::FXColor

bottom

ending color, for bottommost pixels Fox::FXColor



271
 
# File 'rdoc-sources/FXImage.rb', line 271

def vgradient(top, bottom); end

#xshear(shear, color = 0) ⇒ Object

Shear image horizontally and then re-render the server-side image from the client-side pixel buffer. The number of pixels is equal to the shear parameter times 256. The area outside the image is filled with transparent black, unless another color is specified.

Parameters:

shear

how far to shear [Integer]

color

fill color for areas outside the sheared image Fox::FXColor



238
 
# File 'rdoc-sources/FXImage.rb', line 238

def xshear(shear, color=0); end

#yshear(shear, color = 0) ⇒ Object

Shear image verticallyand then re-render the server-side image from the client-side pixel buffer. The number of pixels is equal to the shear parameter times 256. The area outside the image is filled with transparent black, unless another color is specified.

Parameters:

shear

how far to shear [Integer]

color

fill color for areas outside the sheared image Fox::FXColor



251
 
# File 'rdoc-sources/FXImage.rb', line 251

def yshear(shear, color=0); end