SNDNEW: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
(Initial version)
 
No edit summary
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:_SNDNEW}}
{{DISPLAYTITLE:_SNDNEW}}
The [[_SNDNEW]] function creates a raw empty sound in memory and returns a [[LONG]] handle value above 0. The sound's raw memory can then be accessed using [[_MEMSOUND]], [[_MEMGET (function)]] & [[_MEMPUT]].
The '''_SNDNEW''' function creates a raw empty sound in memory and returns a [[LONG]] handle value for later access.




{{PageSyntax}}
{{PageSyntax}}
: {{Parameter|soundHandle&}} = [[_SNDNEW]][({{Parameter|frames&}}, {{Parameter|channels&}}, {{Parameter|bits&}})]
: {{Parameter|soundHandle&}} = [[_SNDNEW]]({{Parameter|frames&}}, {{Parameter|channels&}}, {{Parameter|bits&}})




{{PageParameters}}
{{PageParameters}}
* {{Parameter|frames&}} is the number of sample frames needed.
* {{Parameter|frames&}} is the number of sample frames needed. The number needed for one second of sound is determined by your sound hardware's sample rate, hence you may use the following formula:
** {{InlineCode}}frames& = {{Cl|_SNDRATE}} * neededSeconds!{{InlineCodeEnd}} where you may also specify fractional seconds.
* {{Parameter|channels&}} is the number of channels needed (1 = mono, 2 = stereo).
* {{Parameter|channels&}} is the number of channels needed (1 = mono, 2 = stereo).
* {{Parameter|bits&}} is the number of bits per channel (8 = 8-bit unsigned integer, 16 = 16-bit signed integer, 32 = 32-bit floating point).
* {{Parameter|bits&}} is the number of bits per channel (8 = 8-bit unsigned integer, 16 = 16-bit signed integer, 32 = 32-bit floating point).
Line 14: Line 15:


{{PageDescription}}
{{PageDescription}}
* Use the function to create a raw sound in memory.
* Use this function to create a raw sound in memory.
* Once the sound is created, it can then be accessed using [[_MEMSOUND]], [[_MEMGET (function)]] & [[_MEMPUT]].
* Once the sound is created, it can be accessed and manipulated using the [[_MEM]] interface statements and functions, mainly [[_MEMSOUND]], [[_MEMGET]] & [[_MEMPUT]].
* Using this one can generate sounds once programmatically and play it multiple times.
* Using this function can generate sounds once programmatically and then play it multiple times.
* The sound memory can also be filled with sample data from other sources like files, DATA statements and more!
* The sound memory can also be filled with sample data from other sources like files, [[DATA]] statements and more.
* Sound handle values and the memory used must be freed using [[_SNDCLOSE]] when no longer required.
* Sound memory pointers obtained with [[_MEMSOUND]] must be freed using [[_MEMFREE]] and the Sound handle value itself must be freed using [[_SNDCLOSE]] when no longer required.
* A sample rate ([[_SNDRATE]]) of 48000 means 48000 sample frames / second.
* 1 sample frame = 1 sample x number of channels.




{{PageAvailability}}
{{PageAvailability}}
* '''QBPE 3.5 and up''' (QB64 Phoenix Edition)
* '''QB64-PE v3.5.0 and up'''




{{PageExamples}}
{{PageExamples}}
''Example 1:'' Creating a sound at runtime and playing it.
;Example 1:Creating a sound at runtime and playing it.
{{CodeStart}}
{{CodeStart}}
{{Cl|$CONSOLE}}
{{Cl|OPTION _EXPLICIT}}
{{Cl|OPTION _EXPLICIT}}
{{Cl|OPTION _EXPLICITARRAY}}


{{Cl|RANDOMIZE}} {{Cl|TIMER}}
{{Cl|RANDOMIZE}} {{Cl|TIMER (function)|TIMER}}


{{Cl|CONST}} SOUND_DURATION = 5 ' duration is seconds
{{Cl|CONST}} SOUND_DURATION = 5 ' duration is seconds
Line 69: Line 66:


{{PageSeeAlso}}
{{PageSeeAlso}}
* [[_MEM]], [[_MEMSOUND]]
* [[_MEM]], [[_MEMSOUND]], [[_MEMFREE]]
* [[_MEMPUT]]
* [[_MEMPUT]], [[_MEMGET]], [[_MEMGET (function)]]
* [[_MEMGET]], [[_MEMGET (function)]]
* [[_SNDOPEN]], [[_SNDCLOSE]], [[_SNDRAW]], [[_SNDRATE]]
* [[_MEMFREE]]
 
* [[_SNDOPEN]]
* [[_SNDRAW]]


{{PageNavigation}}
{{PageNavigation}}

Latest revision as of 17:02, 24 February 2023

The _SNDNEW function creates a raw empty sound in memory and returns a LONG handle value for later access.


Syntax

soundHandle& = _SNDNEW(frames&, channels&, bits&)


Parameters

  • frames& is the number of sample frames needed. The number needed for one second of sound is determined by your sound hardware's sample rate, hence you may use the following formula:
    • frames& = _SNDRATE * neededSeconds! where you may also specify fractional seconds.
  • channels& is the number of channels needed (1 = mono, 2 = stereo).
  • bits& is the number of bits per channel (8 = 8-bit unsigned integer, 16 = 16-bit signed integer, 32 = 32-bit floating point).


Description

  • Use this function to create a raw sound in memory.
  • Once the sound is created, it can be accessed and manipulated using the _MEM interface statements and functions, mainly _MEMSOUND, _MEMGET & _MEMPUT.
  • Using this function can generate sounds once programmatically and then play it multiple times.
  • The sound memory can also be filled with sample data from other sources like files, DATA statements and more.
  • Sound memory pointers obtained with _MEMSOUND must be freed using _MEMFREE and the Sound handle value itself must be freed using _SNDCLOSE when no longer required.


Availability

  • QB64-PE v3.5.0 and up


Examples

Example 1
Creating a sound at runtime and playing it.
OPTION _EXPLICIT

RANDOMIZE TIMER

CONST SOUND_DURATION = 5 ' duration is seconds
CONST SAMPLE_CHANNELS = 1 ' number of channes. For stereo we need to add another _MEMPUT below and +offset by SAMPLE_BYTES
CONST SAMPLE_BYTES = 4 ' number of bytes / sample (not frame!)

DIM h AS LONG: h = _SNDNEW(SOUND_DURATION * _SNDRATE, SAMPLE_CHANNELS, SAMPLE_BYTES * 8)
IF (h < 1) THEN
    PRINT "Failed to create sound!"
    END
END IF

DIM sndblk AS _MEM: sndblk = _MEMSOUND(h, 0)
IF sndblk.SIZE = 0 THEN
    _SNDCLOSE h
    PRINT "Failed to access sound data!"
    END
END IF

DIM t AS _INTEGER64
FOR t = 0 TO (SOUND_DURATION * _SNDRATE) - 1
    _MEMPUT sndblk, sndblk.OFFSET + (t * SAMPLE_BYTES * SAMPLE_CHANNELS), SIN(2 * _PI * 440 * t / _SNDRATE) + RND - RND AS SINGLE ' mixes noise and a sine wave
NEXT

_SNDPLAY h

SLEEP SOUND_DURATION

_SNDCLOSE h

END


See also


Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=SNDNEW&oldid=8063"