Sound

Âm thanh ngắn nạp vào bộ nhớ: hiệu ứng, phát chồng, cao độ, lặp. Tiếp...

Enumerations
enum	njin::audio_bus {   njin::bus_master , njin::bus_music , njin::bus_sfx , njin::bus_ui ,   njin::bus_voice , njin::audio_bus_count }
	Kênh trộn âm thanh, như thanh trượt trong menu cài đặt của game. Tiếp...

Các hàm
void	njin::audio_set_bus_volume (context &ctx, audio_bus bus, f32 volume)
	Đặt âm lượng một kênh, từ 0 trở lên (1 là nguyên).
f32	njin::audio_bus_volume (const context &ctx, audio_bus bus)
	Âm lượng một kênh.
void	njin::audio_set_bus_muted (context &ctx, audio_bus bus, bool muted)
	Tắt hoặc bật tiếng cả một kênh, không đụng đến âm lượng đã đặt.
bool	njin::audio_bus_muted (const context &ctx, audio_bus bus)
	Kênh có đang tắt tiếng không.
void	njin::sound_set_bus (context &ctx, sound_handle handle, audio_bus bus)
	Đưa một sound vào kênh khác, ví dụ bus_ui cho tiếng nhấp menu.
sound_handle	njin::sound_load (context &ctx, const char *path)
	Nạp một âm thanh ngắn vào bộ nhớ.
sound_handle	njin::sound_load_samples (context &ctx, const f32 *samples, i32 count, i32 sample_rate)
	Tạo một âm thanh từ các mẫu đã có trong bộ nhớ.
void	njin::sound_unload (context &ctx, sound_handle handle)
	Giải phóng sound.
void	njin::sound_set_volume (context &ctx, sound_handle handle, f32 volume)
	Đặt âm lượng của sound, từ 0 trở lên (1 là âm lượng gốc).
void	njin::sound_set_muted (context &ctx, sound_handle handle, bool muted)
	Tắt hoặc bật tiếng sound.
void	njin::sound_play_once (context &ctx, sound_handle handle)
	Phát sound mà không cắt các bản đang phát.
void	njin::sound_play_once_at (context &ctx, sound_handle handle, f32 pitch, f32 gain)
	Giống sound_play_once() nhưng chỉnh cao độ và độ lớn cho riêng bản này.
void	njin::sound_play_restart (context &ctx, sound_handle handle)
	Cắt mọi bản đang phát rồi phát lại từ đầu, nên lúc nào cũng chỉ nghe một bản.
void	njin::sound_play_loop (context &ctx, sound_handle handle)
	Đánh dấu sound là lặp lại và phát nếu nó chưa phát.
void	njin::sound_play_at (context &ctx, sound_handle handle, vec2 world_pos)
	Phát sound như sound_play_once(), kèm vị trí trong thế giới.
void	njin::audio_set_range (context &ctx, f32 full_until, f32 silent_from)
	Khoảng cách nghe được của sound_play_at().
void	njin::sound_stop (context &ctx, sound_handle handle)
	Dừng mọi bản đang phát của sound và bỏ chế độ lặp.

Mô tả chi tiết

Âm thanh ngắn nạp vào bộ nhớ: hiệu ứng, phát chồng, cao độ, lặp.

Thông tin về Enumeration Type

audio_bus

enum njin::audio_bus

Kênh trộn âm thanh, như thanh trượt trong menu cài đặt của game.

Âm lượng thật của một sound là âm lượng riêng của nó nhân âm lượng kênh của nó nhân bus_master. Music luôn ở kênh bus_music; sound mặc định ở bus_sfx, đổi bằng sound_set_bus().

Enumerator
bus_master	Tổng: nhân vào mọi thứ.
bus_music	Nhạc nền (mọi music).
bus_sfx	Hiệu ứng trong game. Mặc định của sound.
bus_ui	Tiếng giao diện.
bus_voice	Lồng tiếng, tiếng thoại.
audio_bus_count	Số kênh. Không phải một kênh thật.

Thông tin về hàm

audio_set_bus_volume()

void njin::audio_set_bus_volume	(	context &	ctx,
		audio_bus	bus,
		f32	volume )

Đặt âm lượng một kênh, từ 0 trở lên (1 là nguyên).

Áp dụng ngay cho cả những âm đang phát. Lưu cùng cài đặt bằng settings_save().

Các tham số

ctx	Context của engine.
bus	Kênh.
volume	Âm lượng. Giá trị âm được coi là 0.

audio_bus_volume()

f32 njin::audio_bus_volume	(	const context &	ctx,
		audio_bus	bus )

Âm lượng một kênh.

Các tham số

ctx	Context của engine.
bus	Kênh.

Giá trị trả về

Âm lượng, mặc định 1.

audio_set_bus_muted()

void njin::audio_set_bus_muted	(	context &	ctx,
		audio_bus	bus,
		bool	muted )

Tắt hoặc bật tiếng cả một kênh, không đụng đến âm lượng đã đặt.

Các tham số

ctx	Context của engine.
bus	Kênh.
muted	true để tắt tiếng.

audio_bus_muted()

bool njin::audio_bus_muted	(	const context &	ctx,
		audio_bus	bus )

Kênh có đang tắt tiếng không.

Các tham số

ctx	Context của engine.
bus	Kênh.

Giá trị trả về

true nếu đang tắt.

sound_set_bus()

void njin::sound_set_bus	(	context &	ctx,
		sound_handle	handle,
		audio_bus	bus )

Đưa một sound vào kênh khác, ví dụ bus_ui cho tiếng nhấp menu.

Các tham số

ctx	Context của engine.
handle	Sound.
bus	Kênh.

sound_load()

sound_handle njin::sound_load	(	context &	ctx,
		const char *	path )

Nạp một âm thanh ngắn vào bộ nhớ.

Dùng cho hiệu ứng như tiếng bắn, tiếng nhấp. Nhạc nền dài thì dùng music_load(). Handle không hợp lệ hoặc đã unload bị mọi hàm sound bỏ qua. Nếu máy không có thiết bị âm thanh thì việc nạp thất bại và ghi log, còn game vẫn chạy.

Các tham số

ctx	Context của engine.
path	Đường dẫn file âm thanh (wav, ogg, mp3, flac...).

Giá trị trả về

Handle của sound, hoặc handle có id 0 nếu không có thiết bị, file thiếu hoặc không giải mã được.

sound_load_samples()

sound_handle njin::sound_load_samples	(	context &	ctx,
		const f32 *	samples,
		i32	count,
		i32	sample_rate )

Tạo một âm thanh từ các mẫu đã có trong bộ nhớ.

Dữ liệu là mono, số thực 32 bit trong khoảng -1..1. Nó được chép vào bộ đệm riêng của sound và không được giữ lại, nên mảng của bạn có thể bị hủy ngay sau khi hàm trả về. Dùng cho âm thanh game tự sinh ra lúc khởi động.

Các tham số

ctx	Context của engine.
samples	Mảng mẫu.
count	Số mẫu.
sample_rate	Tần số lấy mẫu, ví dụ 44100.

Giá trị trả về

Handle của sound, hoặc handle có id 0 nếu tham số sai hoặc tạo thất bại.

sound_unload()

void njin::sound_unload	(	context &	ctx,
		sound_handle	handle )

Giải phóng sound.

Handle không hợp lệ bị bỏ qua.

Các tham số

ctx	Context của engine.
handle	Sound cần giải phóng.

sound_set_volume()

void njin::sound_set_volume	(	context &	ctx,
		sound_handle	handle,
		f32	volume )

Đặt âm lượng của sound, từ 0 trở lên (1 là âm lượng gốc).

Áp dụng ngay cho cả những bản đang phát. Mặc định là 1. Giá trị âm được coi là 0.

Các tham số

ctx	Context của engine.
handle	Sound cần đặt.
volume	Âm lượng.

sound_set_muted()

void njin::sound_set_muted	(	context &	ctx,
		sound_handle	handle,
		bool	muted )

Tắt hoặc bật tiếng sound.

Tắt tiếng đưa âm lượng đang phát về 0 mà không đụng đến âm lượng đã lưu, nên bật lại thì khôi phục đúng như cũ.

Các tham số

ctx	Context của engine.
handle	Sound cần đặt.
muted	true để tắt tiếng.

sound_play_once()

void njin::sound_play_once	(	context &	ctx,
		sound_handle	handle )

Phát sound mà không cắt các bản đang phát.

Gọi liên tiếp thì các bản chồng lên nhau, tối đa 8 bản cùng lúc. Quá số đó thì bản chạy lâu nhất bị cắt để lấy chỗ. Hợp với âm thanh mà nhiều thứ cùng kích hoạt, để một đám đông được nghe như một đám đông.

Các tham số

ctx	Context của engine.
handle	Sound cần phát.

sound_play_once_at()

void njin::sound_play_once_at	(	context &	ctx,
		sound_handle	handle,
		f32	pitch,
		f32	gain )

Giống sound_play_once() nhưng chỉnh cao độ và độ lớn cho riêng bản này.

pitch 1 là như bản ghi, 2 là cao gấp đôi. gain nhân vào âm lượng của sound cho bản này. Cả hai không được lưu lại: lần phát thường sau đó trở về 1 và 1. Hợp với một âm thanh dùng cho nhiều vật có kích cỡ khác nhau: một bản ghi dùng cho tất cả, vật lớn hơn nghe to hơn và trầm hơn.

Các tham số

ctx	Context của engine.
handle	Sound cần phát.
pitch	Cao độ. Giá trị rất nhỏ được nâng lên mức tối thiểu.
gain	Hệ số âm lượng cho bản này. Giá trị âm được coi là 0.

sound_play_restart()

void njin::sound_play_restart	(	context &	ctx,
		sound_handle	handle )

Cắt mọi bản đang phát rồi phát lại từ đầu, nên lúc nào cũng chỉ nghe một bản.

Hợp với tiếng nhấp giao diện hoặc tiếng cảnh báo: bấm dồn thì nghe rõ từng lần thay vì chồng thành một đống.

Các tham số

ctx	Context của engine.
handle	Sound cần phát.

sound_play_loop()

void njin::sound_play_loop	(	context &	ctx,
		sound_handle	handle )

Đánh dấu sound là lặp lại và phát nếu nó chưa phát.

Module âm thanh của engine phát lại sound mỗi khi thấy nó vừa kết thúc, nên đây là lời gọi duy nhất cần để giữ nó chạy. Vì được phát lại sau khi kết thúc, chỗ nối có một quãng lặng cỡ một frame. Với nhạc nền dài, dùng music_load() để không có quãng lặng. Gọi sound_stop() để dừng.

Các tham số

ctx	Context của engine.
handle	Sound cần phát lặp.

sound_play_at()

void njin::sound_play_at	(	context &	ctx,
		sound_handle	handle,
		vec2	world_pos )

Phát sound như sound_play_once(), kèm vị trí trong thế giới.

Âm lượng giảm dần theo khoảng cách tới điểm camera đang nhìn, và âm thanh lệch sang loa trái hoặc phải theo vị trí trên màn hình. Xem audio_set_range().

Các tham số

ctx	Context của engine.
handle	Sound cần phát.
world_pos	Nơi phát ra tiếng, trong thế giới.

audio_set_range()

void njin::audio_set_range	(	context &	ctx,
		f32	full_until,
		f32	silent_from )

Khoảng cách nghe được của sound_play_at().

Gần hơn full_until thì nghe đủ âm lượng, xa hơn silent_from thì im lặng, ở giữa thì nhỏ dần đều. Mặc định là 200 và 1200 đơn vị thế giới.

Các tham số

ctx	Context của engine.
full_until	Khoảng cách bắt đầu nhỏ dần.
silent_from	Khoảng cách im lặng hẳn. Nhỏ hơn full_until thì được nâng bằng full_until.

sound_stop()

void njin::sound_stop	(	context &	ctx,
		sound_handle	handle )

Dừng mọi bản đang phát của sound và bỏ chế độ lặp.

Các tham số

ctx	Context của engine.
handle	Sound cần dừng.