GetSpriteTexture

From ZDoom Wiki
Jump to navigation Jump to search

State

TextureID, bool, Vector2 GetSpriteTexture(int rotation, int skin = 0, Vector2 scale = (0,0), int spritenum = -1, int framenum = -1)

Usage

A State struct function that can be called on a state pointer to return the TextureID of the sprite associated with that state. (Also returns some additionall information about the sprite.)

At the moment, this is the only way to convert a SpriteID to a TextureID, because direct conversion/casting between those types is not allowed.

Parameters

  • int rotation
A value from 0 to 16 to account for sprite rotations (which support up to 16 angles), with 0 meaning "front", 8 meaning "back" and so on.
  • int skin
An ID to the player skin it's supposed to find. Such as if you're trying to rip a sprite from a player while also accounting for any skin they might have on. The ID can be found by either calling GetSkin() from a PlayerInfo instance. Or checking the global PlayerSkins array. 0 by default, which means that any potential skins are totally ignored.
  • Vector2 scale
Vestigial. Does nothing. Actor sprites are scaled according to the Actor's Scale value, which is readable directly as the scale actor field.
  • int spritenum
If non-negative, this will accept another SpriteID which can be obtained with GetSpriteIndex. If used, the function disregards the state it's being called on and obtains a TextureID for the explicitly provided SpriteID.
  • int framenum
If non-negative, the function will returns the sprite with the given frame letter instead of using the frame letter explicitly associated with the calling state. (0 means frame letter A, 1 means B, and so on.)

Note: If both spritenum and framenum are used, the function becomes essentially a static method that can be used to convert any SpriteID to a TextureID. It still requires a state to be called on, but the state becomes irrelevant, i.e. literally any actor state can be used. For example:

let def = GetDefaultByType('Actor');
TextureID = def.spawnstate.GetSpriteTexture(0, spritenum: GetSpriteIndex("POSS"), framenum: 0);

The code above will explicitly obtain the TextureID for the image POSSA1. We use the base Actor class just to have a state it can be called on, but the state in this case is not relevant. Functionally, this is identical to calling TexMan.CheckForTexture("POSSA1"), the only difference being that you don't need to worry about figuring out the rotation number (which can be 0 or greater depending on whether the sprite in question has rotations or not). It is also more performant, than CheckForTexture.

Return values

  • TextureID
The sprite graphic that is in the state the function was called from. If a skin was passed, the corresponding skin graphic for that state, if any, will be returned.
Warning: Normally, to check if the sprite texture obtained by this function is valid, you would call IsValid() on the obtained TextureID pointer. However, note that TNT1 is also considered valid. This is important, because when an actor's code is loaded but the sprites for that actor aren't, they are automatically remapped to TNT1 by the engine, and as a result GetSpriteTexture() will obtain a "valid" texture, even though there are no sprites for the actor. For cases like this, you will need to manually check if (""..<actor state pointer>.sprite != "TNT1") to make sure the sprite associated with a given state isn't TNT1.
  • bool
Returns if the particular sprite graphic is meant to be mirrored.
  • Vector2
Returns the scale of the sprite graphic. THIS IS ONLY USEFUL FOR VALID SKIN SPRITES, normal sprites do not have any custom scale attached to them for this to return!

Examples

States are available in static context with GetDefaultByType, so this function doesn't require an actor instance to exist. For example, this is valid:

state s = GetDefaultByType('Cacodemon').spawnstate;
TextureID stex = s.GetSpriteTexture(8);
// stex now contains a TextureID for the HEADA5 sprite

(Note, spawnstate is an Actor field that contains a pointer to the first state in the actor's Spawn state sequence.)


Below is a slightly expanded example, demonstrating how a function could be created to obtain the TextureID of the first state in an actor's state sequence:

static TextureID GetStateTextureByType(class<Actor> type, StateLabel label)
{
	TextureID tex;
	tex.SetNull(); //set this to null right away, so we can return a null texture if conditions aren't valid

	let def = Actor.GetDefaultByType(type); //try obtaining the defaults of the specified class
	if (!def) return tex;

	State st = def.FindState(label); //try finding a state by the provided state label
	if (!st) return tex;

	return st.GetSpriteTexture(0); //return the texture of a state
}

The above function can then be called, for example, as GetStateTextureByType('Cacodemon', "Death") — this will obtain HEADG1 as a TextureID.

(See also GetDefaultByType)