Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
AudioStream personalizzati
Introduzione
AudioStream è la classe base di tutti gli oggetti che emettono audio. AudioStreamPlayer si collega a un AudioStream per emettere dati PCM in un AudioServer che gestisce i driver audio.
Tutte le risorse audio richiedono due classi basate sull'audio: AudioStream e AudioStreamPlayback. Come contenitore di dati, AudioStream contiene la risorsa e si espone a GDScript. AudioStream fa riferimento al proprio AudioStreamPlayback personalizzato interno, che traduce AudioStream in dati PCM.
Questa guida presuppone che il lettore sappia come creare moduli C++. Se non, fare riferimento a questa guida Moduli personalizzati in C++.
Riferimenti:
Perché?
Associare librerie esterne (come Wwise, FMOD, ecc.).
Aggiungere code d'attesa audio personalizzate
Aggiungere supporto per più formati audio
Creare un AudioStream
Un AudioStream è costituito da tre componenti: contenitore di dati, nome del flusso e un generatore di classi friend AudioStreamPlayback. È possibile caricare i dati audio in diversi modi, ad esempio tramite un contatore interno per un generatore di toni, un buffer interno/esterno o un riferimento a un file.
Alcuni AudioStream devono essere stateless, come gli oggetti caricati da ResourceLoader. ResourceLoader carica una sola volta e fa riferimento allo stesso oggetto a prescindere dal numero di volte in cui load viene chiamato su una risorsa specifica. Pertanto, lo stato di riproduzione deve essere autonomo in AudioStreamPlayback.
#pragma once
#include "servers/audio/audio_stream.h"
class AudioStreamMyTone : public AudioStream {
GDCLASS(AudioStreamMyTone, AudioStream)
private:
friend class AudioStreamPlaybackMyTone;
public:
virtual Ref<AudioStreamPlayback> instantiate_playback() override;
virtual String get_stream_name() const override;
virtual double get_length() const override { return 0.0; }
virtual void get_parameter_list(List<Parameter> *r_parameters) override;
protected:
static void _bind_methods();
};
#include "audiostream_mytone.h"
#include "audiostream_playback_mytone.h"
Ref<AudioStreamPlayback> AudioStreamMyTone::instantiate_playback() {
Ref<AudioStreamPlaybackMyTone> playback;
playback.instantiate();
playback->base = Ref<AudioStreamMyTone>(this);
playback->init();
return playback;
}
String AudioStreamMyTone::get_stream_name() const {
return "MyTone";
}
void AudioStreamMyTone::get_parameter_list(List<Parameter> *r_parameters) {
r_parameters->push_back(Parameter(PropertyInfo(Variant::FLOAT, "Frequency", PROPERTY_HINT_RANGE, "44.0, 16000.0"), "220.0"));
}
void AudioStreamMyTone::_bind_methods() {}
Riferimenti:
Creare un AudioStreamPlayback
AudioStreamPlayer utilizza il callback mix per ottenere i dati PCM. Il callback deve corrispondere alla frequenza di campionamento e riempire il buffer.
Poiché AudioStreamPlayback è controllato dal thread audio, l'I/O e l'allocazione dinamica della memoria sono proibiti.
#pragma once
#include "servers/audio/audio_stream.h"
class AudioStreamMyTone;
class AudioStreamPlaybackMyTone : public AudioStreamPlayback {
GDCLASS(AudioStreamPlaybackMyTone, AudioStreamPlayback)
friend AudioStreamMyTone;
private:
Ref<AudioStreamMyTone> base;
double pos = 0.0;
float freq_hz = 220.0f;
bool active = false;
public:
virtual ~AudioStreamPlaybackMyTone() = default;
virtual void start(double p_from_pos = 0.0) override;
virtual void stop() override;
virtual bool is_playing() const override;
virtual int get_loop_count() const override;
virtual double get_playback_position() const override;
virtual void seek(double p_time) override;
virtual int mix(AudioFrame *p_buffer, float p_rate_scale, int p_frames) override;
virtual void set_parameter(const StringName &p_name, const Variant &p_value) override;
virtual Variant get_parameter(const StringName &p_name) const override;
protected:
void reset();
bool init();
void generate(AudioFrame *pcm_buf, int size);
void set_freq(float value);
float get_freq() const;
static void _bind_methods();
};
#include "audiostream_playback_mytone.h"
#include <core/math/math_funcs.h>
#include <core/object/class_db.h>
#include <servers/audio/audio_server.h>
void AudioStreamPlaybackMyTone::start(double p_from_pos) {
active = true;
}
void AudioStreamPlaybackMyTone::stop() {
active = false;
}
bool AudioStreamPlaybackMyTone::is_playing() const {
return active;
}
int AudioStreamPlaybackMyTone::get_loop_count() const {
return 0;
}
double AudioStreamPlaybackMyTone::get_playback_position() const {
return 0.0;
}
void AudioStreamPlaybackMyTone::seek(double p_time) {
if (p_time < 0) {
p_time = 0;
}
const float mix_rate = AudioServer::get_singleton()->get_mix_rate();
pos = p_time * mix_rate;
}
int AudioStreamPlaybackMyTone::mix(AudioFrame *p_buffer, float p_rate, int p_frames) {
ERR_FAIL_COND_V(!is_playing(), 0);
if (!is_playing()) {
return 0;
}
generate(p_buffer, p_frames);
return p_frames;
}
void AudioStreamPlaybackMyTone::set_parameter(const StringName &p_name, const Variant &p_value) {
if (p_name == SNAME("Frequency")) {
const float value = p_value;
set_freq(value);
}
}
Variant AudioStreamPlaybackMyTone::get_parameter(const StringName &p_name) const {
if (p_name == SNAME("Frequency")) {
return Variant(get_freq());
}
ERR_FAIL_COND_V(true, Variant());
return Variant{};
}
void AudioStreamPlaybackMyTone::reset() {
seek(0.0);
}
bool AudioStreamPlaybackMyTone::init() {
reset();
return true;
}
void AudioStreamPlaybackMyTone::generate(AudioFrame *pcm_buf, int size) {
if (!active) {
return;
}
const float mix_rate = AudioServer::get_singleton()->get_mix_rate();
for (int i = 0; i < size; i++) {
const float sample = 32767.0f * Math::sin(2.0f * Math::PI * float(pos + i) / (mix_rate / freq_hz));
pcm_buf[i].left = sample;
pcm_buf[i].right = sample;
}
pos += size;
}
void AudioStreamPlaybackMyTone::set_freq(float value) {
freq_hz = CLAMP(value, 44.0f, 16000.0f);
}
float AudioStreamPlaybackMyTone::get_freq() const {
return freq_hz;
}
void AudioStreamPlaybackMyTone::_bind_methods() {
ClassDB::bind_method(D_METHOD("reset"), &AudioStreamPlaybackMyTone::reset);
ClassDB::bind_method(D_METHOD("set_freq", "value"), &AudioStreamPlaybackMyTone::set_freq);
ClassDB::bind_method(D_METHOD("get_freq"), &AudioStreamPlaybackMyTone::get_freq);
}
Utilizzo
The set_freq and get_freq methods allow direct change of the frequency parameter.
But one can also use the more generic way to handle parameters based on properties through get/set("parameters/Frequency").
extends AudioStreamPlayer3D
var control: float = 0.0
func _input(event):
if event.is_action_pressed("play"):
if is_playing():
stop()
else:
play()
control = get_stream_playback().get_freq()
# Parameter equivalent:
# control = get("parameters/Frequency") as float
print(control)
if event.is_action_pressed("up"):
control *= 1.1
set_freq(control)
print(control)
if event.is_action_pressed("down"):
control *= 0.9
set_freq(control)
print(control)
func set_freq(value):
var stream_playback = get_stream_playback()
if stream_playback:
stream_playback.set_freq(control)
# Parameter equivalent:
#set("parameters/Frequency", control)
Ricampionamento
L'AudioServer di Godot utilizza attualmente una frequenza di campionamento di 44.100 Hz. Quando sono necessarie altre frequenze di campionamento, come 48.000 Hz, è necessario specificarne una o utilizzare AudioStreamPlaybackResampled. Godot fornisce un'interpolazione cubica per il ricampionamento audio.
Invece di creare un overload per mix, AudioStreamPlaybackResampled utilizza _mix_internal per interrogare AudioFrames e get_stream_sampling_rate per ottenere la frequenza di mixaggio attuale.