Eiffel Media API
Overview Cluster Class Classes Index      Previous Next      Top Features

em.video

Class EM_SURFACE


Direct ancestors

EM_SHARED_SUBSYSTEMS, EM_SHARED_BITMAP_FACTORY, EM_SHARED_ERROR_HANDLER, EM_CONSTANTS, SDL_SURFACE_STRUCT, SDL_FUNCTIONS_EXTERNAL, SDL_VIDEO_FUNCTIONS_EXTERNAL, SDL_GFXPRIMITIVES_FUNCTIONS_EXTERNAL, SDL_ROTOZOOM_FUNCTIONS_EXTERNAL, DISPOSABLE, DOUBLE_MATH

Known direct descendants

EM_VIDEO_SURFACE, EM_BITMAP, EM_TTF_SURFACE

Creation

Features

Invariants

indexing

description

Drawing surface.

TODO: write explanation of "draw_*" and "put_*"

date

$Date: 2005/10/28 08:41:56 $

revision

$Revision: 1.37 $

class

EM_SURFACE

create {EM_BITMAP_FACTORY}

make_from_pointer (a_pointer: POINTER)

-- Make from a_pointer that is possibly shared within the
-- process of the current OS.

require
a_pointer_not_void: a_pointer /= Default_pointer

feature -- Access

alpha_value: INTEGER

-- Alpha value for Current (per surface)
-- This value will only be used in blitting when alpha transparency is enabled!

clipping_rectangle: EM_RECT

-- Clipping rectangle. Pixels outside this rectangle won't be drawn.
-- (see coordinate_area for according rectangle in user coordinates)

ensure
result_not_void: Result /= Void
coordinate_area: EM_ORTHOGONAL_RECTANGLE

-- Coordinates inside which all drawing primitives can draw,
-- coordinates outside this area will be clipped
-- (usefull to avoid drawing objects, that are anyway off-screen),
-- coordinate_area can be changed using transform_coordinates,
-- translate_coordinates and clip_coordinates.

ensure
result_not_void: Result /= Void
device_line_width: INTEGER

-- Line width used to draw lines with line_width onto surface.

device_resolution: DOUBLE

-- Number of pixels/points on device per user coordinate unit
-- (Usefull for drawing with adopted level of detail
-- for better performance)

ensure
positive_display_resolution: Result > 0
drawing_color: EM_COLOR

-- Color used to draw

item: POINTER

-- Pointer to the wrapped struct

-- (From EWG_STRUCT)

require
exists: exists
ensure
item_not_default_pointer: Result /= Default_pointer
line_width: DOUBLE

-- Line width used to draw lines

lock_calls: INTEGER

-- Number of times lock was called without calling unlock.

pixel_format: EM_PIXELFORMAT

-- Informations about the pixel format of Current

ensure
result_not_void: Result /= Void
pixel_value (an_x, an_y: INTEGER): INTEGER

-- Color value of the pixel at position an_x, an_y in Current
-- Note: For direct pixel access Current has to be locked using lock.

require
surface_locked: is_locked
position_valid: an_x < width and an_x >= 0 and an_y < height and an_y >= 0
resolution: INTEGER

-- Number of bytes per pixel

rotation_angle: DOUBLE

-- Rotation angle of Current in degree

texture: GL_TEXTURE

-- Texture of surface for OpenGL

ensure
texture_not_void: Result /= Void
transparent_colorkey: INTEGER

-- Value of the color that is drawed as transparent when drawing Current
-- onto another surface.

zoom_factor_x: DOUBLE

-- Zoom factor of Current (x-axis)

zoom_factor_y: DOUBLE

-- Zoom factor of Current (y-axis)

feature -- Status report

has_transparent_colorkey: BOOLEAN

-- Has Current a transparent_colorkey?

is_alpha_transparency_enabled: BOOLEAN

-- Is alpha transparency enabled?
-- (either per surface or per pixel)

is_anti_aliasing_enabled: BOOLEAN

-- Is anti aliasing enabled for converting Current and for drawing onto it?

is_line_point_rounding_enabled: BOOLEAN

-- Are points of polylines and line segments drawed rounded
-- for nice line endings and joins between polyline segments?

is_line_width_scaling_enabled: BOOLEAN

-- Does Current scale line width,
-- when coordinates are scaled?
-- (True by default)

is_locked: BOOLEAN

-- Is Current locked?

is_modified: BOOLEAN

-- Was surface modified since last set_unmodified?

is_per_pixel_alpha_enabled: BOOLEAN

-- Is alpha transparency on a per pixel basis enabled?

is_per_surface_alpha_enabled: BOOLEAN

-- Is alpha transparency for Current enabled?

is_rotated: BOOLEAN

-- Is Current rotated?

is_zoomed: BOOLEAN

-- Is Current zoomed?

feature -- Status setting

disable_alpha_transparency

-- Disable alpha transparency for Current.

ensure
alpha_transparency_disabled: not is_alpha_transparency_enabled
disable_anti_aliasing

-- Disable antialiasing on Current.

ensure
antialiasing_disabled: not is_anti_aliasing_enabled
disable_per_pixel_alpha

-- Disable per pixel alpha transparency

ensure
per_pixel_alpha_disabled: not is_per_pixel_alpha_enabled
disable_transparent_colorkey

-- Disable transparent colorkey for blitting Current surface.

ensure
transparent_colorkey_disabled: not has_transparent_colorkey
enable_alpha_transparency

-- Enable alpha transparency for Current.

ensure
alpha_transparency_enabled: is_alpha_transparency_enabled
enable_anti_aliasing

-- Enable antialiasing on Current.

ensure
antialiasing_enabled: is_anti_aliasing_enabled
enable_per_pixel_alpha

-- Enable per pixel alpha transparency.
-- Note: A pixel_format object obtained before calling enable_per_pixel_alpha will be invalid.

ensure
alpha_transparency_enabled: is_alpha_transparency_enabled
per_pixel_alpha_enabled: is_per_pixel_alpha_enabled
per_surface_alpha_disabled: not is_per_surface_alpha_enabled
set_anti_aliasing_enabled (a_bool: BOOLEAN)

-- Set is_anti_aliasing_enabled to a_bool.

ensure
is_anti_aliasing_enabled_set: is_anti_aliasing_enabled = a_bool
set_line_point_rounding_enabled (a_bool: BOOLEAN)

-- Set is_line_point_rounding_enabled to a_bool.

ensure
is_line_point_rounding_enabled_set: is_line_point_rounding_enabled = a_bool
set_line_width_scaling_enabled (a_bool: BOOLEAN)

-- Set is_line_width_scaling_enabled to a_bool.

ensure
is_line_width_scaling_enabled_set: is_line_width_scaling_enabled = a_bool
set_unmodified

-- Clear modified status.

ensure
not_modified: not is_modified

feature -- Element change

set_alpha_value (an_alpha_value: like alpha_value)

-- Enable alpha transparency for Current and set alpha_value to an_alpha_value.
-- This setting is for the whole surface and cannot be used to set per pixel alpha transparency.
-- alpha = 0 is transparent
-- alpha = 255 is opaque
-- Note: an alpha value of 128 is treated special and is optimised
-- Note: this does NOT work in OpenGL mode if Current will be blitted directly on the screen
-- Note: this will disable per pixel alpha

require
an_alpha_value_in_range: 0 <= an_alpha_value and an_alpha_value <= 255
ensure
alpha_value_set: alpha_value = an_alpha_value
alpha_transparency_enabled: is_alpha_transparency_enabled
per_surface_alpha_enabled: is_per_surface_alpha_enabled
per_pixel_alpha_disabled: not is_per_pixel_alpha_enabled
set_clipping_rectangle (a_rectangle: like clipping_rectangle)

-- Set clipping_rectangle to a_rectangle.

require
a_rectangle_not_void: a_rectangle /= Void
set_drawing_color (a_color: like drawing_color)

-- Set drawing_color to a_color.

require
a_color_attached: a_color /= Void
ensure
drawing_color_set: drawing_color.is_equal (a_color)
set_line_width (a_width: like line_width)

-- Set line_width to a_width.

ensure
line_width_assigned: line_width = a_width
set_transparent_color (red: INTEGER; green:INTEGER; blue: INTEGER)

-- Set color (red, green, blue) to be transparent in Current.
-- This will disable per pixel alpha transparency on the surface.

require
red_not_negative: red >= 0
green_not_negative: green >= 0
blue_not_negative: blue >= 0
ensure
per_pixel_alpha_disabled: not is_per_pixel_alpha_enabled
has_transparent_colorkey: has_transparent_colorkey
set_transparent_colorkey (a_colorkey: like transparent_colorkey)

-- Set color a_colorkey to be transparent in Current.
-- This will disable per pixel alpha transparency on the surface.

ensure
per_pixel_alpha_disabled: not is_per_pixel_alpha_enabled
has_transparent_colorkey: has_transparent_colorkey
transparent_colorkey_set: transparent_colorkey = a_colorkey

feature -- Transformation

rotate (angle: DOUBLE)

-- Rotate Current counterclockwise angle degrees.
-- Note: If antialiasing is enabled on Current the rotation can be slow (use prerendering if possible).
-- Note: In most cases this feature changes the dimension of Current.
-- Note: After rotating, no drawing is allowed on Current (but you still can zoom and rotate).

ensure
rotation_angle_set: rotation_angle = old rotation_angle + angle
rotated: is_rotated
stretch (factor_x, factor_y: DOUBLE)

-- Strech Current with factor_x factor_y.
-- Note: If antialiasing is enabled on Current the zooming can be slow (use prerendering if possible).
-- Note: In most cases this feature changes the dimension of Current.
-- Note: After zooming, no drawing is allowed on Current (but you still can zoom and rotate).

ensure
zoom_factor_x_set: zoom_factor_x = old zoom_factor_x * factor_x
zoom_factor_y_set: zoom_factor_y = old zoom_factor_y * factor_y
zoomed: is_zoomed
transform (factor_x, factor_y, angle: DOUBLE)

-- Transform Current with stretchfactors factor_x factor_y and
-- a counterclockwise rotation angle degrees.
-- Note: If antialiasing is enabled on Current the rotation can be slow (use prerendering if possible).
-- Note: In most cases this feature changes the dimension of Current.
-- Note: After rotating, no drawing is allowed on Current (but you still can zoom and rotate).

ensure
zoom_factor_x_set: zoom_factor_x = old zoom_factor_x * factor_x
zoom_factor_y_set: zoom_factor_y = old zoom_factor_y * factor_y
rotation_angle_set: rotation_angle = old rotation_angle + angle
zoomed: is_zoomed
rotated: is_rotated
zoom (factor: DOUBLE)

-- Zoom Current with factor.
-- Note: If antialiasing is enabled on Current the zooming can be slow (use prerendering if possible).
-- Note: In most cases this feature changes the dimension of Current.
-- Note: After zooming, no drawing is allowed on Current (but you still can zoom and rotate).

ensure
zoom_factor_x_set: zoom_factor_x = old zoom_factor_x * factor
zoom_factor_y_set: zoom_factor_y = old zoom_factor_y * factor
zoomed: is_zoomed

feature -- Conversion

device_point (a_point: EM_VECTOR_2D): EM_VECTOR_2D

-- Device point where a_point gets drawed to

require
a_point_not_void: a_point /= Void
ensure
result_calculated: Result /= Void
user_point (a_x, a_y: DOUBLE): EM_VECTOR_2D

-- Point in user coordinates that gets drawed
-- to device point at x and y

ensure
result_calculated: Result /= Void

feature -- Miscellaneous

clip_coordinates (an_area: EM_ORTHOGONAL_RECTANGLE)

-- Clip coordinate_area to an_area.
-- Usefull to restrict drawing to an_area
-- and to just not draw anything outside.
-- (Reset by calling again with backed up old coordinate_area
-- when done clipping)

require
an_area_not_void: an_area /= Void
disable_scaling_coordinates (a_reference_point: EM_VECTOR_2D)

-- Transform coordinates such as no scaling is done anymore and use
-- a_reference_point as the point that keeps its position.
-- (Reset by calling transform_coordinates with backed up
-- old coordinate_area when done)

require
a_reference_point_not_void: a_reference_point /= Void
lock

-- Lock Current to enable direct pixel access.
-- Note: Every lock must have an unlock.
-- If lock is called multiple times then so must unlock

ensure
lock_calls_increased: lock_calls = old lock_calls + 1
locked: is_locked
transform_coordinates (an_area: EM_ORTHOGONAL_RECTANGLE)

-- Transform coordinate_area to an_area.
-- Usefull for drawable containers that want there children to
-- be drawed scaled (zoomed or stretched).
-- (Reset it by calling again with backed up old coordinate_area when done).

require
an_area_not_void: an_area /= Void
translate_coordinates (a_distance: EM_VECTOR_2D)

-- Draw all following drawing primitives as translated by a_distance.
-- Usefull for container drawables that want there children to
-- be drawed relatively to a new origin-point.
-- (Reset by calling again with negation of a_distance when done)

require
a_distance_not_void: a_distance /= Void
unlock

-- Unlock Current.
-- Note: Current is only unlocked if unlock is called lock_calls times.

require
surface_locked: is_locked
ensure
lock_calls_decreased: lock_calls = old lock_calls - 1

feature -- Drawing

clear

-- Clear Current surface with black color.

require
not_rotated: not is_rotated
not_zoomed: not is_zoomed
fill (a_color: EM_COLOR)

-- Fill surface with a_color.

require
a_color_not_void: a_color /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed

feature -- Drawing (with coordinate transformation)

draw_bitmap (a_bitmap: EM_BITMAP)

-- Draw a_bitmap into its bounding_box onto Current.

require
a_bitmap_not_void: a_bitmap /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_bitmap_part (a_bitmap: EM_BITMAP; part_rectangle: EM_ORTHOGONAL_RECTANGLE)

-- Draw part of a_bitmap specified by part_rectangle
-- at its original position inside a_bitmap.bounding_box onto Current.

require
a_bitmap_not_void: a_bitmap /= Void
part_rectangle_not_void: part_rectangle /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_line_segment (point1, point2: EM_VECTOR_2D)

-- Draw line segment from point1 to point2 using current line_width and drawing_color.

require
point1_attached: point1 /= Void
point2_attached: point2 /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_object (an_object: EM_DRAWABLE)

-- Draw an_object.

require
an_object_not_void: an_object /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_point (a_point: EM_VECTOR_2D)

-- Draw a point at position a_point with width line_width using drawing_color.
-- Draw exactly one pixel if line_width is 0.0.

require
a_point_attached: a_point /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_polygon (points: DS_LINEAR [EM_VECTOR_2D])

-- Draw polygon defined by points with line_width and drawing_color.

require
at_least_three_points: points /= Void and then points.count >= 3
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_polyline (points: DS_LINEAR [EM_VECTOR_2D])

-- Draw line segments between subsequent points in points.

require
at_least_two_points: points /= Void and then points.count >= 2
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_rectangle (a_rectangle: EM_ORTHOGONAL_RECTANGLE)

-- Draw a_rectangle with line_width and drawing_color.

require
a_rectangle_not_void: a_rectangle /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_surface_part_stretched (a_surface: EM_SURFACE; part_rectangle: EM_ORTHOGONAL_RECTANGLE; a_destination_box: EM_ORTHOGONAL_RECTANGLE)

-- Draw part of a_surface specified by part_rectangle into a_destination_box onto Current, stretch if necessary.

require
a_surface_not_void: a_surface /= Void
part_rectangle_not_void: part_rectangle /= Void
a_destination_box_not_void: a_destination_box /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
draw_surface_stretched (a_surface: EM_SURFACE; a_destination_box: EM_ORTHOGONAL_RECTANGLE)

-- Draw a_surface into a_destination_box onto Current, stretch if necessary.

require
a_surface_not_void: a_surface /= Void
a_destination_box_not_void: a_destination_box /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
fill_polygon (points: DS_LINEAR [EM_VECTOR_2D])

-- Draw filled polygon defined by points in drawing_color.

require
at_least_three_points: points /= Void and then points.count >= 3
not_rotated: not is_rotated
not_zoomed: not is_zoomed
fill_rectangle (a_rectangle: EM_ORTHOGONAL_RECTANGLE)

-- Draw filled rectangle a_rectangle in drawing_color.

require
a_rectangle_not_void: a_rectangle /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed

feature -- Drawing (whitout coordinate transfromation)

blit_surface (a_surface: EM_SURFACE; a_x: INTEGER; a_y: INTEGER)

-- Blit a_surface at a_x and a_y onto Current.

require
a_surface_not_void: a_surface /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
blit_surface_part (a_surface: EM_SURFACE; a_x, a_y, a_width, a_height: INTEGER; a_dest_x, a_dest_y: INTEGER)

-- Blit a_surface part from a_x and a_y to a_width and a_height onto Current at dest_x, dest_y.

require
a_surface_not_void: a_surface /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_circle (center_x, center_y: INTEGER; radius: INTEGER; color: EM_COLOR)

-- Draw circle with center center_x, center_y and radius radius with color onto Current.

require
color_not_void: color /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_circle_filled (center_x, center_y: INTEGER; radius: INTEGER; color: EM_COLOR)

-- Draw filled circle around center at center_x and center_y
-- with radius filled with color onto Current.

require
color_not_void: color /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_line_segment (x1, y1, x2, y2: INTEGER; color: EM_COLOR)

-- Draw a line segment from pixel x1, y1 to pixel x2, y2 with color onto Current.

require
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_pixel (x_pos, y_pos: INTEGER; a_color: EM_COLOR)

-- Draw a pixel at pixel position x_pos, y_pos with color a_color onto Current.

require
a_color_not_void: a_color /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_pixel_value (x_pos, y_pos: INTEGER; a_color_value: INTEGER)

-- Draw a pixel at pixel position x_pos, y_pos with color value a_color_value onto Current.

require
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_polygon (x_coordinates, y_coordinates: EM_INTEGER_ARRAY; count: INTEGER; color: EM_COLOR)

-- Draw polygon defined by first count points
-- in x_coordinates and y_coordinates
-- with color onto Current.

require
x_coordinates_not_void: x_coordinates /= Void
y_coordinates_not_void: y_coordinates /= Void
enough_x_coordinates: x_coordinates.count >= count
enough_y_coordinates: y_coordinates.count >= count
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_polygon_filled (x_coordinates, y_coordinates: EM_INTEGER_ARRAY; count: INTEGER; color: EM_COLOR)

-- Draw filled polygon defined by first count points
-- in x_coordinates and y_coordinates
-- filled with color onto Current.

require
at_least_3_points: count >= 3
x_coordinates_not_void: x_coordinates /= Void
y_coordinates_not_void: y_coordinates /= Void
enough_x_coordinates: x_coordinates.count >= count
enough_y_coordinates: y_coordinates.count >= count
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_rectangle (x1, y1, x2, y2: INTEGER; color: EM_COLOR)

-- Draw rectangle from pixel x1, y1 to pixel x2, y2 with color onto Current.

require
color_not_void: color /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_rectangle_filled (x1, y1, x2, y2: INTEGER; color: EM_COLOR)

-- Draw a filled rectangle from pixel x1, y1
-- to pixel x2, y2 filled with color onto Current.

require
color_not_void: color /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
put_wide_line_segment (x1, y1, x2, y2: INTEGER; a_line_width: INTEGER; color: EM_COLOR)

-- Draw a line segment from pixel x1, y1 to pixel x2, y2
-- with color and a_line_width onto Current.
-- (Implementation just draws a rectangular polygon for the line segment)

require
color_not_void: color /= Void
not_rotated: not is_rotated
not_zoomed: not is_zoomed
set_pixel (a_x, a_y: INTEGER; a_color: EM_COLOR)

-- Set pixel at position a_x a_y to a_color.
-- Note: For direct pixel access Current has to be locked using lock.
-- Note: This feature uses direct memory access. So use put_pixel in normal cases.

require
surface_locked: is_locked
x_coordinate_valid: 0 <= a_x and a_x < width
y_coordinate_valid: 0 <= a_y and a_y < height
a_color_not_void: a_color /= Void
ensure
pixel_set: pixel_value (a_x, a_y) = pixel_format.color_to_pixel_value (a_color)
set_pixel_value (a_x, a_y: INTEGER; a_value: INTEGER)

-- Set pixel at position a_x a_y to a_value.
-- Note: For direct pixel access Current has to be locked using lock.
-- Note: This feature uses direct memory access. So use put_pixel in normal cases.

require
surface_locked: is_locked
x_coordinate_valid: 0 <= a_x and a_x < width
y_coordinate_valid: 0 <= a_y and a_y < height
ensure
pixel_set: pixel_value (a_x, a_y) = a_value

feature {ANY} -- Member Access

flags: INTEGER

-- Access member flags

-- (From SDL_SURFACE_STRUCT)

require
exists: exists
ensure
result_correct: Result = get_flags_external (item)
format: POINTER

-- Access member format

-- (From SDL_SURFACE_STRUCT)

require
exists: exists
ensure
result_correct: Result = get_format_external (item)
height: INTEGER

-- Access member h

-- (From SDL_SURFACE_STRUCT)

require
exists: exists
ensure
result_correct: Result = get_h_external (item)
pixels: POINTER

-- Access member pixels

-- (From SDL_SURFACE_STRUCT)

require
exists: exists
ensure
result_correct: Result = get_pixels_external (item)
width: INTEGER

-- Access member w

-- (From SDL_SURFACE_STRUCT)

require
exists: exists
ensure
result_correct: Result = get_w_external (item)

invariant

drawing_color_not_void: drawing_color /= Void
line_width_not_negative: line_width >= 0
exists: exists
either_per_pixel_or_per_surface_alpha: is_alpha_transparency_enabled implies is_per_pixel_alpha_enabled xor is_per_surface_alpha_enabled

-- From ANY
reflexive_equality: standard_is_equal (Current)
reflexive_conformance: conforms_to (Current)

-- From EWG_STRUCT
managed_data_not_void: managed_data /= Void
managed_capacity_equals_sizeof: exists implies managed_data.capacity = sizeof

end