surface.c File Reference

Surface buffers used to draw images. More...

Functions
const char *	tex_format_name (tex_format_t fmt)
	Return the name of the texture format as a string (for debugging purposes)
surface_t	surface_alloc (tex_format_t format, uint16_t width, uint16_t height)
	Allocate a new surface in memory.
void	surface_free (surface_t *surface)
	Free the buffer allocated in a surface.
surface_t	surface_make_sub (surface_t *parent, uint16_t x0, uint16_t y0, uint16_t width, uint16_t height)
	Initialize a surface_t structure, pointing to a rectangular portion of another surface.
surface_t	surface_make (void *buffer, tex_format_t format, uint16_t width, uint16_t height, uint16_t stride)
	Initialize a surface_t structure with the provided buffer.
tex_format_t	surface_get_format (const surface_t *surface)
	Returns the pixel format of a surface.
surface_t	surface_make_linear (void *buffer, tex_format_t format, uint16_t width, uint16_t height)
	Initialize a surface_t structure with the provided linear buffer.
bool	surface_has_owned_buffer (const surface_t *surface)
	Checks whether this surface owns the buffer that it contains.

Detailed Description

Surface buffers used to draw images.

Function Documentation

surface_alloc()

surface_t surface_alloc	(	tex_format_t	format,
		uint16_t	width,
		uint16_t	height
	)

Allocate a new surface in memory.

This function allocates a new surface with the specified pixel format, width and height. The surface must be freed via surface_free when it is not needed anymore.

A surface allocated via surface_alloc can be used as a RDP frame buffer (passed to rdpq_attach) because it is guaranteed to have the required alignment of 64 bytes, provided it is using one of the formats supported by RDP as a framebuffer target (FMT_RGBA32, FMT_RGBA16 or FMT_I8).

Parameters

[in]	format	Pixel format of the surface
[in]	width	Width in pixels
[in]	height	Height in pixels

Returns

The initialized surface

surface_free()

void surface_free

(

surface_t *

surface

)

Free the buffer allocated in a surface.

This function should be called after a surface allocated via surface_alloc is not needed anymore.

Calling this function on surfaces allocated via surface_make or surface_make_sub (that is, surfaces initialized with an existing buffer pointer) has no effect but clearing the contents of the surface structure.

Parameters

[in]

surface

The surface to free

surface_make_sub()

surface_t surface_make_sub	(	surface_t *	parent,
		uint16_t	x0,
		uint16_t	y0,
		uint16_t	width,
		uint16_t	height
	)

Initialize a surface_t structure, pointing to a rectangular portion of another surface.

The surface returned by this function will point to a portion of the buffer of the parent surface, and will have of course the same pixel format.

Parameters

[in]	parent	Parent surface that will be pointed to
[in]	x0	X coordinate of the top-left corner within the parent surface
[in]	y0	Y coordinate of the top-left corner within the parent surface
[in]	width	Width of the surface that will be returned
[in]	height	Height of the surface that will be returned

Returns

The initialized surface

surface_make()

surface_t surface_make ( void *  buffer, tex_format_t  format, uint16_t  width, uint16_t  height, uint16_t  stride  )

externinline

Initialize a surface_t structure with the provided buffer.

This functions initializes a surface_t structure with the provided buffer and information. It is just a helper to fill the structure fields.

It is not necessary to call surface_free on surfaces created by surface_make as there is nothing to free: the provided buffer will not be owned by the structure, so it is up to the caller to handle its lifetime.

If you plan to use this format as RDP framebuffer, make sure that the provided buffer respects the required alignment of 64 bytes, otherwise rdpq_attach will fail.

Parameters

[in]	buffer	Pointer to the memory buffer
[in]	format	Pixel format
[in]	width	Width in pixels
[in]	height	Height in pixels
[in]	stride	Stride in bytes (length of a row)

Returns

The initialized surface

See also

surface_make_linear

surface_get_format()

tex_format_t surface_get_format ( const surface_t *  surface )

externinline

Returns the pixel format of a surface.

Parameters

[in]

surface

Surface

Returns

The pixel format of the provided surface

surface_make_linear()

surface_t surface_make_linear ( void *  buffer, tex_format_t  format, uint16_t  width, uint16_t  height  )

externinline

Initialize a surface_t structure with the provided linear buffer.

This function is similar to surface_make, but it works for images that are linearly mapped with no per-line padding or extraneous data.

Compared to surface_make, it does not accept a stride parameter, and calculate the stride from the width and the pixel format.

Parameters

[in]	buffer	Pointer to the memory buffer
[in]	format	Pixel format
[in]	width	Width in pixels
[in]	height	Height in pixels

Returns

The initialized surface

See also

surface_make

surface_has_owned_buffer()

bool surface_has_owned_buffer ( const surface_t *  surface )

externinline

Checks whether this surface owns the buffer that it contains.

Parameters

[in]

surface

Surface

Returns

True if this surface owns the buffer; false otherwise