<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<script type="text/javascript" language="JavaScript">
function reDo() {
if (innerWidth != origWidth || innerHeight != origHeight)
location.reload();
}
if ((parseInt(navigator.appVersion) == 4) && (navigator.appName == "Netscape")) {
origWidth = innerWidth;
origHeight = innerHeight;
onresize = reDo;
}
onerror = null;
</script>
<style type="text/css">
< !-- div.WebHelpPopupMenu {
position: absolute;
left: 0px;
top: 0px;
z-index: 4;
visibility: hidden;
}
p.WebHelpNavBar {
text-align: right;
}
-->
</style>
<script type="text/javascript">
gRootRelPath = "../../..";
gCommonRootRelPath = "../../..";
gTopicId = "9.2.17.0_2";
<script type="text/javascript" src="../../../template/scripts/rh.min.js"></script>
<script type="text/javascript" src="../../../template/scripts/common.min.js"></script>
<script type="text/javascript" src="../../../template/scripts/topic.min.js"></script>
<script type="text/javascript" src="../../../template/scripts/topicwidgets.min.js"></script>
<script type="text/javascript" src="../../../whxdata/projectsettings.js"></script>
<link rel="stylesheet" type="text/css" href="../../../template/styles/topic.min.css"/>
<link rel="stylesheet" type="text/css" href="../../../template/Charcoal_Grey/topicheader.css"/>
<meta name="topic-status" content="Draft"/>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>buffer_create</title>
<meta name="generator" content="Adobe RoboHelp 2019"/>
<link rel="stylesheet" href="../../../assets/css/default.css" type="text/css"/>
<meta name="rh-authors" content="Mark Alexander"/>
<meta name="topic-comment" content="Reference page for buffer_create"/>
<meta name="rh-index-keywords" content="buffer_create,buffer_fixed,buffer_grow,buffer_wrap,buffer_fast,buffer_vbuffer"/>
<meta name="search-keywords" content="buffer_create,buffer_fixed,buffer_grow,buffer_wrap,buffer_fast,buffer_vbuffer"/>
</head>
<body>
<div class="topic-header rh-hide" id="rh-topic-header" onclick="rh._.goToFullLayout()">
<div class="logo">
</div>
<div class="nav">
<div class="title" title="buffer_create">
<span>buffer_create</span>
</div>
<div class="gotohome" title="Click here to see this page in full context">
<span>Click here to see this page in full context</span>
</div>
</div>
</div>
<div class="topic-header-shadow rh-hide" id="rh-topic-header-shadow"></div>
<h1>buffer_create</h1>
<p>You use this function to allocate a portion of memory as a buffer in your game, with the function returning the unique <i>buffer id</i> that should be stored in a variable and used for all further function calls to the buffer. The buffer can then be
used to store different types of data (specified when you write to the buffer using the <a href="buffer_write.htm"><tt>buffer_write()</tt></a> function, with the following constants being used to define the buffer type:</p>
<p> </p>
<table>
<tbody>
<tr>
<th>Constant</th>
<th>Description</th>
</tr>
<tr>
<td>buffer_fixed</td>
<td>A buffer of fixed size.</td>
</tr>
<tr>
<td>buffer_grow</td>
<td>A buffer that will "grow" dynamically as data is added</td>
</tr>
<tr>
<td>buffer_wrap</td>
<td>A buffer where the data will "wrap". When the data being added reaches the limit of the buffer size, the overwrite will be placed back at the start of the buffer, and further writing will continue from that point.</td>
</tr>
<tr>
<td>buffer_fast</td>
<td>Special "stripped" buffer that is extremely fast to read/write to. Can only be used with <tt>buffer_u8</tt> <a href="buffer_read.htm">data types</a>, and <i>must</i> be 1 byte aligned.</td>
</tr>
<tr>
<td>buffer_vbuffer</td>
<td>This type of buffer is to be used as a vertex buffer only.</td>
</tr>
</tbody>
</table>
<p> </p>
<p>Apart from the buffer type, you will also have to set the <i>byte alignment</i> for the buffer. This value will vary depending on the data that you wish to store in the buffer, and in most cases a value of 1 is perfectly fine. However, be aware that
for some operations a specific alignment is <i>essential</i>, and an incorrect alignment may cause errors (for further details on alignment see <a href="../../../Additional_Information/Guide_To_Using_Buffers.htm">Buffers</a>). The following is a general
guide to show which values are most appropriate for each data type (when in doubt, use an alignment of 1):</p>
<ul class="colour">
<li>Strings should be aligned to 1 byte.</li>
<li>Signed or unsigned 8bit integers can be aligned to any value, but note that for a fast buffer (see <a href="buffer_write.htm"><tt>buffer_write()</tt></a>) it <i>must</i> be aligned to 1.</li>
<li>Signed or unsigned 16bit integers should be aligned to 2 bytes.</li>
<li>Signed or unsigned 32bit integers should be aligned to 4 bytes</li>
<li>Floats of up to 16bits should be aligned to 2 bytes. <i>(Not currently supported!)</i></li>
<li>Floats of up to 32bits should be aligned to 4 bytes.</li>
<li>Floats of up to 64bits should be aligned to 8 bytes.</li>
</ul>
<p class="note"><b>NOTE</b>: Byte alignment can be very important as the wrong choice may adversely affect performance.</p>
<p class="note"><b>NOTE</b>: It's important that you remove any dynamically created resources like this from memory when you no longer need them to prevent memory leaks, so when you are finished with the buffer that you have created you should free it up again
using <span style="font-size:1px;"><a href="buffer_delete.htm"><tt style="font-size: 14px">buffer_delete()</tt></a></span>.</p>
<p> </p>
<h4>Syntax:</h4>
<p class="code">buffer_create(size, type, alignment)</p>
<table>
<tbody>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td>size</td>
<td>The size (in bytes) of the buffer.</td>
</tr>
<tr>
<td>type</td>
<td>The type of buffer to create (see the constants list above).</td>
</tr>
<tr>
<td>alignment</td>
<td>The byte alignment for the buffer</td>
</tr>
</tbody>
</table>
<p> </p>
<h4>Returns:</h4>
<p class="code">Int (Vertex buffer ID)</p>
<p> </p>
<h4>Example:</h4>
<p class="code">player_buffer = buffer_create(16384, buffer_fixed, 2);</p>
<p>The above code allocates 16384 bytes of memory to a buffer and returns the index of that buffer, which is stored in the variable "player_buffer", for future use. The buffer is aligned to a two byte boundary.</p>
<p> </p>
<p> </p>
<p> </p>
<div class="footer">
<div class="buttons">
<div class="clear">
<div style="float:left">Back: <a href="Buffers.htm">Buffers</a></div>
<div style="float:right">Next: <a href="buffer_create_from_vertex_buffer.htm">buffer_create_from_vertex_buffer</a></div>
</div>
</div>
<h5>© Copyright YoYo Games Ltd. 2020 All Rights Reserved</h5>
</div>
</body></html>