pH Reference Guide

The "ph_create" Function #

Syntax:

ph_create(width, height, [shape], [label], [font], [col1], [col2], [xorig], [yorig]);
Argument Type Description
width real Sets the width of the placeholder, in pixels
height
real Sets the height of the placeholder, in pixels
[shape]
integer/macro Optional: Sets the placeholder shape to rectangle (0), roundrect (1), circle (2), or triangle (3)
[label]
string Optional: Sets a custom string label to display in place of the placeholder resolution
[font]
font Optional: Sets a custom font to display label in
[col1]
color Optional: Sets a custom placeholder background color
[col2]
color Optional: Sets a custom placeholder foreground (border and font) color
[xorig]
real Optional: Sets a custom horizontal sprite origin point, relative to the top-left corner
[yorig]
real Optional: Sets a custom vertical sprite origin point, relative to the top-left corner

Description:

Creates a new placeholder which is stored in memory as a sprite asset, for use with regular sprite functions. This script may be run directly within sprite functions themselves (e.g. draw_sprite) or assigned to a variable for future use.

Generated placeholders are cached so that no two identical placeholders exist at the same time. If a placeholder with the same properties as another is referenced, it will be drawn from memory rather than generated anew. As such, while it is generally not necessary, if large numbers of unique placeholders are used, it may be a good idea to remove them from memory when they are no longer needed by running the ph_free function.

Although only width and height values are required to generate a new placeholder, other options may be added to customize drawing features as desired. To use the default values for any of these arguments, -1 may be supplied instead of a custom value. In the case of shapes, pH also provides macros which can be supplied in place of plain integers, including ph_rect, ph_roundrect, ph_circ, and ph_tri. It is generally recommended to use these macros for clarity and to ensure that generated shapes do not change with updates to pH itself.

Example:

my_sprite = ph_create(320, 240);
draw_sprite(my_sprite, image_index, x, y);
draw_sprite_ext(ph_create(128, 256, ph_roundrect, "Hello, world!", fnt_Arial, c_blue, c_aqua, 64, 128), image_index, x, y, 2, 1, 45, c_red, 0.75);
Last updated on August 14, 2018
Suggest Edit