module Fox
#
# 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
#
class FXImage < FXDrawable
# [deprecated] Pixel data {FXMemoryBuffer}
attr_reader :data
# Array of colors of all image pixels. Can also be written as String of raw [RGBA] values.
attr_accessor :pixels
# Option flags [Integer]
attr_accessor :options
#
# 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 {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]
#
def initialize(a, pixels=nil, opts=0, width=1, height=1) # :yields: theImage
end
#
# 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]
#
def setPixels(pixels, opts=0, width=nil, height=nil)
end
#
# 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.
def pixel_string(offset=nil, size=nil) ; end
#
# 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]
#
def getPixel(x, y) ; end
#
# 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 {FXColor}
#
def setPixel(x, y, clr) ; end
# Scan the image and return +false+ if it's fully opaque.
def hasAlpha?; end
#
# 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.
#
def restore() ; end
#
# Render the image from client-side pixel buffer, if there is data
# and if the image width and height are greater than zero.
#
def render() ; end
#
# 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.
#
def release(); end
#
# 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]
#
def scale(w, h, quality=0) ; end
#
# 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]
#
def mirror(horizontal, vertical) ; end
#
# 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]
#
def rotate(degrees) ; end
#
# 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 {FXColor}
#
def crop(x, y, w, h, color=0) ; end
# Fill image with uniform color.
def fill(color); end
#
# 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 {FXColor}
# +factor+:: fading factor [Integer]
#
def fade(color, factor=255); end
#
# 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 {FXColor}
#
def xshear(shear, color=0); end
#
# 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 {FXColor}
#
def yshear(shear, color=0); end
#
# Fill image using a horizontal gradient.
#
# ==== Parameters:
#
# +left+:: starting color, for leftmost pixels {FXColor}
# +right+:: ending color, for rightmost pixels {FXColor}
#
def hgradient(left, right); end
#
# Fill image using a vertical gradient.
#
# ==== Parameters:
#
# +top+:: starting color, for topmost pixels {FXColor}
# +bottom+:: ending color, for bottommost pixels {FXColor}
#
def vgradient(top, bottom); end
#
# Fill image using a bilinear gradient.
#
# ==== Parameters:
#
# +topleft+:: pixel color for top-left corner {FXColor}
# +topright+:: pixel color for top-right corner {FXColor}
# +bottomleft+:: pixel color for bottom-left corner {FXColor}
# +bottomright+:: pixel color for bottom-right corner {FXColor}
#
def gradient(topleft, topright, bottomleft, bottomright); end
#
# Blend image over uniform color.
#
# ==== Parameters:
#
# +color+:: the blended color {FXColor}
#
def blend(color); end
#
# 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 {FXStream}
#
def savePixels(store) ; end
#
# 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 {FXStream}
#
def loadPixels(store) ; end
end
end