Âm thanh 3D

Tai nghe, tiếng theo vị trí và entity trong thế giới 3D: khoảng cách, trái phải, Doppler, nón, vật che. Tiếp...

Classes
struct	njin::audio_listener3d
	Tai nghe của thế giới 3D: mọi tiếng 3D được nghe từ đây. Tiếp...
struct	njin::sound3d_desc
	Cách nghe một tiếng 3D. Tiếp...
struct	njin::voice3d_mix
	Những gì engine tính được cho một tiếng 3D ở lần cập nhật gần nhất, để debug hoặc để vẽ chỉ báo tiếng động trên màn hình. Tiếp...

Enumerations
enum	njin::audio_rolloff { njin::rolloff_inverse , njin::rolloff_linear , njin::rolloff_exponential }
	Cách âm lượng giảm theo khoảng cách, từ min_distance (đủ to) đến max_distance (im). Tiếp...

Các hàm
void	njin::audio_set_listener3d (context &ctx, const audio_listener3d &listener)
	Đặt tai nghe bằng tay.
void	njin::audio_listener3d_follow_camera (context &ctx, bool follow=true)
	Cho tai nghe đi theo camera của begin_3d() (mặc định), hoặc thôi đi theo và đứng yên ở chỗ hiện tại.
audio_listener3d	njin::audio_listener3d_get (const context &ctx)
	Tai nghe đang dùng, kể cả khi nó đi theo camera.
void	njin::audio_set_speed_of_sound (context &ctx, f32 units_per_second)
	Tốc độ âm thanh, đơn vị thế giới mỗi giây, cho hiệu ứng Doppler.
voice3d_handle	njin::sound_play3d (context &ctx, sound_handle handle, vec3 position, const sound3d_desc &desc={})
	Phát một lần handle tại position, nghe từ tai nghe 3D theo desc.
voice3d_handle	njin::sound_play3d (context &ctx, sound_handle handle, entt::entity entity, const sound3d_desc &desc={})
	Như bản trên, nhưng tiếng đi theo entity (vị trí njin::transform3d của nó) cho đến khi phát xong.
voice3d_handle	njin::sound_loop3d (context &ctx, sound_handle handle, vec3 position, const sound3d_desc &desc={})
	Phát lặp handle tại position cho đến khi voice3d_stop() (hoặc sound_stop() cho sound đó): tiếng máy nổ, lửa tí tách, thác nước.
voice3d_handle	njin::sound_loop3d (context &ctx, sound_handle handle, entt::entity entity, const sound3d_desc &desc={})
	Như bản trên, nhưng tiếng đi theo entity: tiếng máy gắn vào xe.
void	njin::voice3d_set_position (context &ctx, voice3d_handle voice, vec3 position)
	Dời tiếng tới position, và thôi đi theo entity nếu đang đi theo.
void	njin::voice3d_attach (context &ctx, voice3d_handle voice, entt::entity entity, vec3 offset={})
	Cho tiếng đi theo entity, lệch offset so với vị trí của nó (trong thế giới, không xoay theo entity).
void	njin::voice3d_set_velocity (context &ctx, voice3d_handle voice, vec3 velocity)
	Đặt vận tốc của nguồn cho Doppler.
void	njin::voice3d_set_desc (context &ctx, voice3d_handle voice, const sound3d_desc &desc)
	Đổi cách nghe của tiếng đang phát: âm lượng theo ga của xe, cao độ theo vòng tua máy (vehicle3d_rpm()).
sound3d_desc	njin::voice3d_desc (const context &ctx, voice3d_handle voice)
	Cách nghe đang dùng của tiếng.
void	njin::voice3d_stop (context &ctx, voice3d_handle voice)
	Dừng tiếng.
bool	njin::voice3d_playing (const context &ctx, voice3d_handle voice)
	Tiếng còn đang phát không (tiếng lặp thì cho đến khi dừng).
voice3d_mix	njin::voice3d_state (const context &ctx, voice3d_handle voice)
	Âm lượng, trái phải và cao độ của tiếng ở lần cập nhật gần nhất.

Mô tả chi tiết

Tai nghe, tiếng theo vị trí và entity trong thế giới 3D: khoảng cách, trái phải, Doppler, nón, vật che.

Thông tin về Enumeration Type

audio_rolloff

enum njin::audio_rolloff

Cách âm lượng giảm theo khoảng cách, từ min_distance (đủ to) đến max_distance (im).

Enumerator
rolloff_inverse	Giảm theo 1/khoảng cách, như ngoài đời: nhanh lúc gần, chậm lúc xa. Ở 10% cuối trước max_distance nhỏ dần về 0 để không tắt đột ngột. Mặc định.
rolloff_linear	Giảm đều từ 1 ở min_distance đến 0 ở max_distance. Dễ đoán, hợp với game cần biết chắc tiếng nghe được tới đâu.
rolloff_exponential	Giảm theo lũy thừa của khoảng cách, (d / min_distance)^-rolloff_factor: tắt nhanh hơn inverse. Cùng nhỏ dần ở 10% cuối như inverse.

Thông tin về hàm

audio_set_listener3d()

void njin::audio_set_listener3d	(	context &	ctx,
		const audio_listener3d &	listener )

Đặt tai nghe bằng tay.

Từ lúc này tai thôi đi theo camera, cho đến khi gọi audio_listener3d_follow_camera(). Giá trị không hữu hạn (NaN, vô cực) bị bỏ qua.

Các tham số

ctx	Context của engine.
listener	Tai nghe. Vận tốc 0 thì không có Doppler do tai di chuyển.

audio_listener3d_follow_camera()

void njin::audio_listener3d_follow_camera	(	context &	ctx,
		bool	follow = true )

Cho tai nghe đi theo camera của begin_3d() (mặc định), hoặc thôi đi theo và đứng yên ở chỗ hiện tại.

Các tham số

ctx	Context của engine.
follow	true để đi theo camera.

audio_listener3d_get()

audio_listener3d njin::audio_listener3d_get

(

const context &

ctx

)

Tai nghe đang dùng, kể cả khi nó đi theo camera.

Các tham số

ctx	Context của engine.

Giá trị trả về

Tai nghe.

audio_set_speed_of_sound()

void njin::audio_set_speed_of_sound	(	context &	ctx,
		f32	units_per_second )

Tốc độ âm thanh, đơn vị thế giới mỗi giây, cho hiệu ứng Doppler.

Mặc định 343 (mét mỗi giây, khi một đơn vị là một mét). Nhỏ hơn thì Doppler rõ hơn.

Các tham số

ctx	Context của engine.
units_per_second	Tốc độ. Không dương thì bị bỏ qua.

sound_play3d() [1/2]

voice3d_handle njin::sound_play3d	(	context &	ctx,
		sound_handle	handle,
		vec3	position,
		const sound3d_desc &	desc = {} )

Phát một lần handle tại position, nghe từ tai nghe 3D theo desc.

Mỗi tiếng 3D có giọng riêng nên âm lượng, trái phải và cao độ của nó được tính lại mỗi frame từ vị trí của nó và của tai. Âm lượng cuối cùng còn nhân âm lượng của sound và kênh của nó (sound_set_bus(), audio_set_bus_volume()). Tối đa 64 tiếng 3D cùng lúc; quá số đó thì tiếng phát một lần đã chạy lâu nhất bị cắt. Vị trí không hữu hạn (NaN, vô cực) thì không phát.

Các tham số

ctx	Context của engine.
handle	Sound đã nạp.
position	Nơi phát, trong thế giới.
desc	Cách nghe.

Giá trị trả về

Handle của tiếng, hoặc handle có id 0 nếu không phát được.

sound_play3d() [2/2]

voice3d_handle njin::sound_play3d	(	context &	ctx,
		sound_handle	handle,
		entt::entity	entity,
		const sound3d_desc &	desc = {} )

Như bản trên, nhưng tiếng đi theo entity (vị trí njin::transform3d của nó) cho đến khi phát xong.

Entity bị hủy thì tiếng phát nốt ở chỗ cuối cùng.

Các tham số

ctx	Context của engine.
handle	Sound đã nạp.
entity	Entity có njin::transform3d.
desc	Cách nghe.

Giá trị trả về

Handle của tiếng, hoặc handle có id 0 nếu không phát được.

sound_loop3d() [1/2]

voice3d_handle njin::sound_loop3d	(	context &	ctx,
		sound_handle	handle,
		vec3	position,
		const sound3d_desc &	desc = {} )

Phát lặp handle tại position cho đến khi voice3d_stop() (hoặc sound_stop() cho sound đó): tiếng máy nổ, lửa tí tách, thác nước.

Như sound_play_loop(), chỗ nối có một quãng lặng cỡ một frame.

Các tham số

ctx	Context của engine.
handle	Sound đã nạp.
position	Nơi phát, trong thế giới.
desc	Cách nghe.

Giá trị trả về

Handle của tiếng, hoặc handle có id 0 nếu không phát được.

sound_loop3d() [2/2]

voice3d_handle njin::sound_loop3d	(	context &	ctx,
		sound_handle	handle,
		entt::entity	entity,
		const sound3d_desc &	desc = {} )

Như bản trên, nhưng tiếng đi theo entity: tiếng máy gắn vào xe.

Entity bị hủy thì tiếng lặp dừng luôn.

Các tham số

ctx	Context của engine.
handle	Sound đã nạp.
entity	Entity có njin::transform3d.
desc	Cách nghe.

Giá trị trả về

Handle của tiếng, hoặc handle có id 0 nếu không phát được.

voice3d_set_position()

void njin::voice3d_set_position	(	context &	ctx,
		voice3d_handle	voice,
		vec3	position )

Dời tiếng tới position, và thôi đi theo entity nếu đang đi theo.

Không hữu hạn thì bị bỏ qua.

Các tham số

ctx	Context của engine.
voice	Tiếng.
position	Vị trí mới, trong thế giới.

voice3d_attach()

void njin::voice3d_attach	(	context &	ctx,
		voice3d_handle	voice,
		entt::entity	entity,
		vec3	offset = {} )

Cho tiếng đi theo entity, lệch offset so với vị trí của nó (trong thế giới, không xoay theo entity).

Các tham số

ctx	Context của engine.
voice	Tiếng.
entity	Entity có njin::transform3d.
offset	Độ lệch.

voice3d_set_velocity()

void njin::voice3d_set_velocity	(	context &	ctx,
		voice3d_handle	voice,
		vec3	velocity )

Đặt vận tốc của nguồn cho Doppler.

Mặc định engine đo vận tốc từ quãng nguồn đi mỗi frame; gọi hàm này thì engine thôi đo và dùng giá trị này (ví dụ lấy từ body3d_velocity()) cho đến khi tiếng dừng.

Các tham số

ctx	Context của engine.
voice	Tiếng.
velocity	Vận tốc, đơn vị mỗi giây.

voice3d_set_desc()

void njin::voice3d_set_desc	(	context &	ctx,
		voice3d_handle	voice,
		const sound3d_desc &	desc )

Đổi cách nghe của tiếng đang phát: âm lượng theo ga của xe, cao độ theo vòng tua máy (vehicle3d_rpm()).

Các tham số

ctx	Context của engine.
voice	Tiếng.
desc	Cách nghe mới.

voice3d_desc()

sound3d_desc njin::voice3d_desc	(	const context &	ctx,
		voice3d_handle	voice )

Cách nghe đang dùng của tiếng.

Sửa bản sao rồi voice3d_set_desc().

Các tham số

ctx	Context của engine.
voice	Tiếng.

Giá trị trả về

Cách nghe, hoặc giá trị mặc định nếu handle không hợp lệ.

voice3d_stop()

void njin::voice3d_stop	(	context &	ctx,
		voice3d_handle	voice )

Dừng tiếng.

Handle không còn hợp lệ nữa.

Các tham số

ctx	Context của engine.
voice	Tiếng.

voice3d_playing()

bool njin::voice3d_playing	(	const context &	ctx,
		voice3d_handle	voice )

Tiếng còn đang phát không (tiếng lặp thì cho đến khi dừng).

Các tham số

ctx	Context của engine.
voice	Tiếng.

Giá trị trả về

true nếu còn phát.

voice3d_state()

voice3d_mix njin::voice3d_state	(	const context &	ctx,
		voice3d_handle	voice )

Âm lượng, trái phải và cao độ của tiếng ở lần cập nhật gần nhất.

Các tham số

ctx	Context của engine.
voice	Tiếng.

Giá trị trả về

Kết quả, hoặc giá trị mặc định nếu handle không hợp lệ.