Public Types
enum	ResizeAlgorithm { None = 0 , scale2x , scale3x , scale4x , hq2x , hq3x , hq4x }
	Available pixel rescaling algorithms. More...
enum	Access { Invalid = 0 , Static = SDL_TEXTUREACCESS_STATIC , Streaming = SDL_TEXTUREACCESS_STREAMING , RenderTarget = SDL_TEXTUREACCESS_TARGET }
typedef Texture	self_type

Public Member Functions
	Texture (void)
	Default constructor.
	~Texture (void)
	Destructor.
	Texture (const Texture &copy)
	Copy constructor.
Texture &	operator= (const Texture &other)
	Copy assignment operator.
Texture *	clone () const
	Get a shallow-copy of the underlying stored texture.
bool	initialize (uint32 format, uint32 flags, int width, int height)
bool	initialize (uint32 format, uint32 flags, const Size2i &dims)
bool	create (SDL_Texture *source)
bool	create (const Image &source)
bool	create (const Image &source, uint32 pixel_format, enum Texture::Access type)
const Point2i &	position () const
const Size2i &	size () const
	Get the width & height dimensions of the texture.
const IntRect &	bounds () const
SDL_Texture *	texture () const
	Get the underlying texture stored.
bool	valid () const
	Is this object initialized – not nullptr?
enum Texture::Access	access (void) const
	Query texture access type.
void	set_position (const Point2i &pos)
void	set_size (const Size2i &size)
	Set the width & height dimensions of the texture.
void	set_bounds (const IntRect &bounds)
	Set bounding coordinates of the Texture.
int32	width (void) const
int32	height (void) const
int	pitch (void) const
void *	pixels (void) const
uint8	bytes_per_pixel (void) const
uint32	pixel_format (void) const
uint8	bits_per_pixel (void) const
const SDL_BlendMode	blend_mode (void) const
	Obtain the blending mode used for texture copies.
const Color4i &	colorkey (void) const
uint8	alpha (void) const
	Obtain the set color key for this image.
const Color4i	color_modulation (void) const
	Obtain the additional color value multiplied into render copy operations.
bool	locked () const
	Query lock status of texture.
bool	lock ()
	Lock the entire bounds of the texture for write access to the pixel buffer.
bool	lock (const IntRect &bounds)
	Lock a portion of the texture for write access to the pixel buffer.
void	unlock (void)
bool	load (const std::string &filename, bool use_cache=false, enum Texture::Access type=Access::Static)
bool	update_pixels (const void *source, uint16 pitch, const IntRect &bounds)
	Upload pixels to texture.
void	draw (SDL_Renderer *target) const
void	draw (const RenderWindow &target) const
void	draw (SDL_Renderer *target, const real64 angle) const
void	draw (const RenderWindow &target, const real64 angle) const
bool	set_alpha (uint8 opacity)
	Set an additional alpha value multiplied into render copy operations.
uint32	pixel (int x, int y)
	Read a RGBA pixel from the video surface.
bool	resize (enum ResizeAlgorithm scaling_algorithm)
	Rescale the Texture with the chosen rescaling algorithm.
int	scale_factor (enum ResizeAlgorithm scaling_algorithm) const
	Return the scaling factor of the chosen algorithm.
int	scale_factor () const
bool	set_blend_mode (const SDL_BlendMode blend)
	Set a new blending mode for this texture.
bool	set_colorkey (const Color4i &colorkey)
bool	set_color_modulation (const Color4i &color)
	Set an additional color value multiplied into render copy operations.
bool	copy_pixels (const void *source, int pitch)

Static Public Member Functions
static const Point2i	maximum_size (void)
	Obtain the largest nom::Texture size allowable by your graphics hardware.

Private Member Functions
void	set_scale_factor (int factor)

Private Attributes
std::shared_ptr< SDL_Texture >	texture_
void *	pixels_
	Texture's pixels; these are only available when a Texture is locked.
int	pitch_
	Texture's pixel pitch; these are only available when a Texture is locked.
Point2i	position_
Size2i	size_
IntRect	bounds_
Color4i	colorkey_
	Cached upon use of the set_colorkey method for use by external classes.
int	scale_factor_

Detailed Description

Definition at line 53 of file Texture.hpp.

Member Typedef Documentation

◆ self_type

typedef Texture nom::Texture::self_type

Definition at line 56 of file Texture.hpp.

Member Enumeration Documentation

◆ Access

enum nom::Texture::Access

Definition at line 70 of file Texture.hpp.

◆ ResizeAlgorithm

enum nom::Texture::ResizeAlgorithm

Available pixel rescaling algorithms.

Definition at line 59 of file Texture.hpp.

Constructor & Destructor Documentation

◆ Texture()

nom::Texture::Texture ( void )

Default constructor.

Todo

position_ should be initialized to Point2i::null.

bounds_ should be initialized to IntRect::null.

colorkey_ should be initialized to Color4i::null.

◆ ~Texture()

nom::Texture::~Texture ( void )

Destructor.

Remarks: Frees any pixel data associated with the Texture; The video surface – if locked – will be unlocked at this time before freeing its memory.

Member Function Documentation

◆ access()

enum Texture::Access nom::Texture::access ( void ) const

Query texture access type.

Returns: Texture::Access enumeration

◆ alpha()

uint8 nom::Texture::alpha ( void ) const

Obtain the set color key for this image.

Returns: Value between Color4i::ALPHA_OPAQUE and Color4i::ALPHA_TRANSPARENT.

◆ bits_per_pixel()

uint8 nom::Texture::bits_per_pixel ( void ) const

Calculate this object's bits per pixel (color depth)

Returns: Integer value of 8, 16, 24 or 32 on success; 32-bit if the color depth is unknown.

◆ clone()

Texture * nom::Texture::clone ( ) const

Get a shallow-copy of the underlying stored texture.

Returns: A pointer to a new nom::Texture instance from the stored data of this object's instance. The returned pointer is owned by the caller.

Remarks: The cloned instance shares the same internal texture memory. If a deep-copy clone is required, you should either keep the nom::Image source used to create the texture's pixel buffer and clone from it instead. Alternatives may include using a Render To Texture target or nom::Renderer::pixels.

◆ color_modulation()

const Color4i nom::Texture::color_modulation ( void ) const

Obtain the additional color value multiplied into render copy operations.

Returns: nom::Color4i on success; nom::Color4i::null on err

◆ colorkey()

const Color4i & nom::Texture::colorkey ( void ) const

Obtain the set color key for this image

Returns: Returns non-negative nom::Color on success; nom::Color::null on failure

◆ create() [1/3]

bool nom::Texture::create ( const Image & source )

Remarks: Texture::Access::Static type

◆ create() [2/3]

bool nom::Texture::create	(	const Image &	source,
		uint32	pixel_format,
		enum Texture::Access	type )

Remarks: For creation of textures of access types: Access::Streaming and Access::RenderTarget.

◆ create() [3/3]

bool nom::Texture::create ( SDL_Texture * source )

See also: Image::texture

◆ draw() [1/4]

void nom::Texture::draw ( const RenderWindow & target ) const

Draw a nom::Texture to a nom::RenderWindow target

Parameters

nom::RenderWindow

Note: This is an alias for nom::Texture::draw ( SDL_Renderer* )

◆ draw() [2/4]

void nom::Texture::draw	(	const RenderWindow &	target,
		const real64	angle ) const

Draw a rotated nom::Texture on a nom::RenderWindow

Parameters

target	Reference to an active nom::RenderWindow
angle	Rotation angle in degrees

◆ draw() [3/4]

void nom::Texture::draw ( SDL_Renderer * target ) const

Draw a nom::Texture to a SDL_Renderer target

Parameters

SDL_Renderer

◆ draw() [4/4]

void nom::Texture::draw	(	SDL_Renderer *	target,
		const real64	angle ) const

Draw a rotated nom::Texture to a rendering target

Parameters

target	Pointer to SDL_Renderer context
angle	Rotation angle in degrees

Todo: Implement pivot point & make use of SDL_RendererFlip enum

◆ height()

int32 nom::Texture::height ( void ) const

Obtain height, in pixels, of texture

Returns: -1 on error; non-zero height on success

◆ initialize() [1/2]

bool nom::Texture::initialize	(	uint32	format,
		uint32	flags,
		const Size2i &	dims )

See also: ::intialize(uint32 format, uint32 flags, int width, int height)

◆ initialize() [2/2]

bool nom::Texture::initialize	(	uint32	format,
		uint32	flags,
		int	width,
		int	height )

Initialize an object with specified parameters

Parameters

width	Width – in pixels – of the new texture
height	Height – in pixels – of the new texture
format	A pixel format; one of the enumerated values in SDL_PixelFormatEnum
flags	Texture access type; one of the enumerated values in SDL_TextureAccess

◆ load()

bool nom::Texture::load	(	const std::string &	filename,
		bool	use_cache = false,
		enum Texture::Access	type = Access::Static )

Load an image into memory from a file

Parameters

filename	File path you wish to load into memory as a valid bitmap / texture (think: supported image file types).
type	nom::Texture::Access enumeration type
use_cache	Whether or not to use an internal object cache feature of nomlib. Defaults to off.

Todo: Test/Research Texture caching – nom::ObjectCache worked beautifully with SDL_Surface, is the same true of SDL_Texture?

Todo: merge 'use_cache' in with 'flags'

◆ lock() [1/2]

bool nom::Texture::lock ( )

Lock the entire bounds of the texture for write access to the pixel buffer.

Remarks: Texture must have been created as the Access::Streaming type.

◆ lock() [2/2]

bool nom::Texture::lock ( const IntRect & bounds )

Lock a portion of the texture for write access to the pixel buffer.

Parameters

bounds The area encompassing the area to lock; pass IntRect::null to lock the entire surface of the texture.

Remarks: Texture must have been created as the Access::Streaming type.

◆ maximum_size()

const Point2i nom::Texture::maximum_size ( void )

static

Obtain the largest nom::Texture size allowable by your graphics hardware.

Returns: A new Point2i object filled in with width (x) and height (y) values, in pixel units.

Note: The values obtained here are dependent upon the nom::Renderer context used at the time of creation of the nom::Texture – in other words, whichever nom::RenderWindow was active at the time of the nom::Texture creation.

◆ pixel()

uint32 nom::Texture::pixel	(	int	x,
		int	y )

Read a RGBA pixel from the video surface.

Returns: A 32-bit encoded color value, dependent upon the pixel format.

Remarks: You are responsible for any necessary video surface locking and unlocking.

Note: The color depth is determined by the existing color depth of the nom::Image – 8-bit, 15/16-bit, 24-bit or 32-bit bits per pixel depths are supported. When a color depth cannot be determined, it is assumed 32-bit.

Todo: Test 8-bit, 15/16-bit & 24-bit pixel blits

◆ resize()

bool nom::Texture::resize ( enum ResizeAlgorithm scaling_algorithm )

Rescale the Texture with the chosen rescaling algorithm.

Note: See the ResizeAlgorithm enum for available rescaling algorithms.

Remarks: This method call requires that the existing Texture is of the Texture::Access::Streaming type. Once resized, the rescaled texture is of the Texture::Access::Static type and therefore cannot be modified again without the complete re-initialization of the original buffer (image file).

Todo: Improve err handling of this method when ScaleX & HQX algorithms are not built. (Perhaps log a message warning the user that since the algorithms are not built in, that SDL2's bilinear rescaling will be used instead???)

◆ set_alpha()

bool nom::Texture::set_alpha ( uint8 opacity )

Set an additional alpha value multiplied into render copy operations.

Remarks: Upon rendering, the following formula is used for the alpha modulation: srcA = srcA * ( alpha / 255 )

◆ set_color_modulation()

bool nom::Texture::set_color_modulation ( const Color4i & color )

Set an additional color value multiplied into render copy operations.

Parameters

nom::Color4i red, green & blue values multiplied into color operations

Returns: TRUE on success; FALSE on failure

Remarks: SDL2 color modulation formula: srcC = srcC * ( color / 255 )

◆ set_colorkey()

bool nom::Texture::set_colorkey ( const Color4i & colorkey )

Set a new color key

Parameters

colorkey nom::Color object representing the RGB pixel to be marked transparent.

Todo: ERR check on locking call, etc.

(This method requires locking the texture; use wisely!).

Remarks: This method converts a a color key to a fully transparent alpha channel.

◆ set_size()

void nom::Texture::set_size ( const Size2i & size )

Set the width & height dimensions of the texture.

Remarks: If the width or height dimensions are greater than the original source dimensions, they will automatically be rescaled.

◆ size()

const Size2i & nom::Texture::size ( ) const

Get the width & height dimensions of the texture.

Remarks: This method return invalid results if the bounds has not been set.

Todo: We need to decide if we ought to return the dimensions as per what SDL has on record, or if we should use cached values.

◆ unlock()

void nom::Texture::unlock ( void )

Unlock the texture; signals the OK to upload the pixel buffer to the GPU

Remarks: The storage for the pixel buffer will be deleted from memory.

◆ update_pixels()

bool nom::Texture::update_pixels	(	const void *	source,
		uint16	pitch,
		const IntRect &	bounds )

Upload pixels to texture.

Parameters

source	Pixels to upload to the texture
pitch	Pitch of the source pixels
bounds	Rectangle bounds area to update; IntRect::null to update the entire texture

Remarks: This is intended for use with Texture::Access::Static texture types. When used with Texture::Access::Streaming texture types, you may not get the pixels back if you lock the texture afterwards.

◆ width()

int32 nom::Texture::width ( void ) const

Obtain width, in pixels, of texture

Returns: -1 on error; non-zero width on success

Member Data Documentation

◆ bounds_

IntRect nom::Texture::bounds_

private

Position & size of texture within memory; X, Y, width & height in pixels.

Remarks: These coordinates are generally not used unless we are reading pixels from a larger texture than what is rendered – in other words: these are used for sprite sheets, and are also known as clipping bounds.

Definition at line 407 of file Texture.hpp.

◆ colorkey_

Color4i nom::Texture::colorkey_

private

Cached upon use of the set_colorkey method for use by external classes.

Definition at line 410 of file Texture.hpp.

◆ pitch_

int nom::Texture::pitch_

private

Texture's pixel pitch; these are only available when a Texture is locked.

Definition at line 391 of file Texture.hpp.

◆ pixels_

void* nom::Texture::pixels_

private

Texture's pixels; these are only available when a Texture is locked.

Definition at line 388 of file Texture.hpp.

◆ position_

Point2i nom::Texture::position_

private

Rendering position & size – X, Y, width & height – in pixels.

Remarks: Rescaling of the rendered pixels can be done by modifying the width & height members.

Definition at line 397 of file Texture.hpp.

◆ scale_factor_

int nom::Texture::scale_factor_

private

Definition at line 412 of file Texture.hpp.

◆ size_

Size2i nom::Texture::size_

private

Definition at line 399 of file Texture.hpp.

◆ texture_

std::shared_ptr<SDL_Texture> nom::Texture::texture_

private

Definition at line 385 of file Texture.hpp.

The documentation for this class was generated from the following file:

/home/jeff/Projects/nomlib.git/include/nomlib/graphics/Texture.hpp

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ self_type

Member Enumeration Documentation

◆ Access

◆ ResizeAlgorithm

Constructor & Destructor Documentation

◆ Texture()

◆ ~Texture()

Member Function Documentation

◆ access()

◆ alpha()

◆ bits_per_pixel()

◆ clone()

◆ color_modulation()

◆ colorkey()

◆ create() [1/3]

◆ create() [2/3]

◆ create() [3/3]

◆ draw() [1/4]

◆ draw() [2/4]

◆ draw() [3/4]

◆ draw() [4/4]

◆ height()

◆ initialize() [1/2]

◆ initialize() [2/2]

◆ load()

◆ lock() [1/2]

◆ lock() [2/2]

◆ maximum_size()

◆ pixel()

◆ resize()

◆ set_alpha()

◆ set_color_modulation()

◆ set_colorkey()

◆ set_size()

◆ size()

◆ unlock()

◆ update_pixels()

◆ width()

Member Data Documentation

◆ bounds_

◆ colorkey_

◆ pitch_

◆ pixels_

◆ position_

◆ scale_factor_

◆ size_

◆ texture_