X1The "ph_create" Function
Syntax#
| 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.